Smcp help
Explain and help configure the subagent-mcp addon in Claude Code and Codex without any API dependency. Use when the user says "smcp help", "subagent-mcp help", "/smcp:help", "how do I configure providers", "routing table", "what is subagent-mcp", "swarm", or "sub-orchestrator". Covers marketplace and npm-global install, providers.jsonc slot semantics, .env key setup, the doctor/rollback/upgrade CLI commands, and the agentic-swarm workflow.From its SKILL.md
npx -y skills add Heretyc/subagent-mcp --skill smcp-helpAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.3 KB, as published. Nobody here has run it
subagent-mcp Help
Answer questions about installing, configuring, and maintaining the subagent-mcp addon. This skill is documentation only: it explains commands and config shape. It never edits configs or runs installs on its own. It works identically in Claude Code and Codex and needs no network or API access.
What subagent-mcp is
subagent-mcp is an MCP stdio server plus per-turn orchestration-mode hooks
that let a host CLI (Claude Code or Codex) launch and manage background
subagents. The server exposes tools such as launch_agent, poll_agent,
wait, get_status, orchestration-mode, swarm, and the handoff-* set.
Providers and their routing preferences live in a user-owned providers.jsonc;
secrets live only in a sibling .env.
The swarm tool coaches a 7-stage agentic workflow for objectives projected
to span multiple sessions. Call swarm() to start; the server tracks the
current stage in memory and returns per-stage coaching with the exact next call.
Stage 6 dispatches sub-orchestrators -- use launch_agent with
sub-orchestrator: true (main orchestrator only) to launch a child as a
delegate-only orchestrator; its own sub-agents run as normal workers.
Scope note for this release: as of v3.0.0, provider routing slots are live
routing config. They record per-category priority order, are validated and
reported (see doctor and get_status), and are consumed by the slot router
to route matching task categories to the configured API provider.
Install
Marketplace plugin (Claude Code)
Bundles the MCP server and the per-turn hook in one plugin.
claude plugin marketplace add Heretyc/subagent-mcp
claude plugin install subagent-mcp@subagent-mcp
install takes <plugin-name>@<marketplace-name>; both are subagent-mcp.
Add --scope user (default, all projects) or --scope project. Restart the
session after installing.
Codex equivalent
Codex has a plugin marketplace too. Install the bundled plugin with:
codex plugin marketplace add Heretyc/subagent-mcp
codex plugin add subagent-mcp@subagent-mcp
Or register just the server with the official Codex command, which writes
~/.codex/config.toml:
codex mcp add subagent-mcp -- node /abs/path/to/subagent-mcp/dist/index.js
Wire the per-turn hook by copying the repo's codex/hooks.json template into
~/.codex/hooks.json, then run /hooks in a Codex session and trust it.
npm global
Installs the CLI and server to the global npm tree (a copy, not a symlink):
npm install -g @heretyc/subagent-mcp
After a global install you still register the server and hook with each vendor using the vendor commands above.
Configure providers (providers.jsonc)
Run subagent-mcp config init to scaffold providers.jsonc and .env under
the config home (~/.subagent-mcp), which is outside git by default. Re-run
with --force to overwrite (it backs up the old file first). Each provider is
an object under providers:
{
"providers": {
"example": {
"display_name": "Example provider",
"command": "example-cli",
"args": [],
"key_env": "EXAMPLE_PROVIDER_API_KEY",
"routing": {
"math_proof": -1,
"security_review": -1,
"debugging": -1,
"quality_review": -1,
"architecture": -1,
"agentic_execution": -1,
"data_analysis": -1,
"coding": -1,
"knowledge_synthesis": -1,
"mechanical": -1,
"prompt_engineering": -1,
"vulnerability_research": -1,
"molecular_biology": -1,
"ml_accelerator_design": -1
}
}
}
}
Slot semantics
Each routing value is a slot number for that task category:
slot = N(N >= 1) inserts this provider at position N in that category's priority order, shifting any existing entries at or below N down by one.slot < 1(for example-1) disables this provider for that category.- There is no global default priority: a provider participates in a category only when it has an explicit slot of 1 or greater there.
- List all 14 task categories on every provider so coverage is explicit.
The categories are:
math_proof,security_review,debugging,quality_review,architecture,agentic_execution,data_analysis,coding,knowledge_synthesis,mechanical,prompt_engineering,vulnerability_research,molecular_biology,ml_accelerator_design.
Slots are validated, reported, and consumed by the v3.0.0 routing engine. A
provider with -1 for every category is configured but will not receive routed
API tasks.
Set keys (.env)
Credentials never go in providers.jsonc. Instead each provider names an env
var via key_env (key indirection), and the actual secret lives in a .env
file next to providers.jsonc under ~/.subagent-mcp:
EXAMPLE_PROVIDER_API_KEY=sk-your-real-key
config init scaffolds .env with one KEY=YOUR_KEY_HERE line per distinct
key_env it finds. Fill in the real values there and keep .env out of git.
Maintenance commands
subagent-mcp doctor- non-interactive health check of install, wiring, config, and keys. Use the/smcp:doctorskill to run and interpret it.subagent-mcp upgrade- one-command upgrade with backup, hook repair, and a follow-up doctor run.subagent-mcp rollback- restore the most recent config backup (asks for confirmation before restoring).subagent-mcp config init [--force]- scaffoldproviders.jsoncand.env; existing files are skipped unless--force, which overwrites them after a backup.subagent-mcp config validate- check thatproviders.jsoncparses and is well formed.
For live session state (loaded providers, agent count, recent routing
decisions) use the /smcp:status skill, which calls the get_status MCP tool.