SubMCP

SubMCP

An MCP server that gives Claude Code, Cursor, Codex, Windsurf, or Zed the ability to delegate bounded subtasks to sub-agents running on your own NVIDIA NIM account.

Default model: stepfun-ai/step-3.7-flash.

Why

Two reasons, both about your context window.

Context offload. "Trace how auth flows through this service" costs twenty file reads. Do it in your main session and those twenty files sit in your context for the rest of the conversation. Delegate it and the sub-agent burns NIM tokens reading them — you get back a report. The expensive part happens somewhere else, on a model you pay NVIDIA for, and your assistant's context stays clean for the work that actually needs it.

Parallel fan-out. Four independent questions become four sub-agents running at once on one connection, instead of four sequential round trips through your main model. One delegate_parallel call, one answer, every report in it.

Sub-agents are read-only and sandboxed by default. You opt into writes and shell.

Quickstart — Claude Code plugin (recommended)

/plugin install Animuni-Express/submcp

Claude Code prompts you once for your NVIDIA NIM API key (get one at https://build.nvidia.com) and stores it securely (OS keychain, or ~/.claude/.credentials.json where no keychain is available) — no plaintext .env needed. The server runs via uvx straight from this repo, so there's no local clone or venv to manage. Ask your assistant to call list_agents after installing to confirm the key and sandbox are wired up.

Everything below is for manual setup: other MCP clients (Cursor, Codex, Windsurf, Zed), or running from a local clone instead of the plugin.

Quickstart — manual clone

git clone https://github.com/Animuni-Express/submcp.git && cd submcp
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .     # Windows
# .venv/bin/python -m pip install -e .           # macOS / Linux

cp .env.example .env       # then put your key in it, or set it in the client config below

Get a key at https://build.nvidia.com. Then wire the server into your client (next section) and ask your assistant to call list_agents — it needs no API key and will tell you straight away whether the key, the sandbox root, and the gates are what you expect.

MCP client configuration

Every example runs the venv interpreter directly. Don't use a bare python — the client won't have your venv activated, and submcp won't be importable.

Replace <path-to-submcp> with the absolute path to your own checkout. Windows paths in JSON need doubled backslashes.

Claude Code

CLI (project scope — writes .mcp.json for you):

claude mcp add submcp --scope project \
  --env NVIDIA_API_KEY=nvapi-... \
  -- "<path-to-submcp>/.venv/Scripts/python.exe" -m submcp

Use --scope user instead to make it available in every project.

Or write .mcp.json in the repo root by hand:

{
  "mcpServers": {
    "submcp": {
      "command": "<path-to-submcp>\\.venv\\Scripts\\python.exe",
      "args": ["-m", "submcp"],
      "env": {
        "NVIDIA_API_KEY": "nvapi-..."
      }
    }
  }
}

Check it with claude mcp list, or /mcp inside a session.

Cursor

.cursor/mcp.json in the project (or ~/.cursor/mcp.json globally) — same shape:

{
  "mcpServers": {
    "submcp": {
      "command": "<path-to-submcp>\\.venv\\Scripts\\python.exe",
      "args": ["-m", "submcp"],
      "env": {
        "NVIDIA_API_KEY": "nvapi-..."
      }
    }
  }
}

Then enable submcp under Settings → MCP.

Codex

~/.codex/config.toml — TOML, and the table is mcp_servers (underscore):

[mcp_servers.submcp]
command = "<path-to-submcp>/.venv/Scripts/python.exe"
args = ["-m", "submcp"]

[mcp_servers.submcp.env]
NVIDIA_API_KEY = "nvapi-..."

Windsurf / Zed / anything else

Any client that speaks stdio MCP takes the same three things: the command (<venv>/Scripts/python.exe), the args (["-m", "submcp"]), and an env block with NVIDIA_API_KEY.

Timeouts

A delegation is a whole agent loop — up to SUBMCP_MAX_STEPS model calls. SubMCP's own ceiling is SUBMCP_TIMEOUT (240s default). If your host kills the tool call first you lose the report even though the sub-agent finished, so raise the host's limit above SubMCP's. In Claude Code that's MCP_TOOL_TIMEOUT (milliseconds), set in the client environment, e.g. MCP_TOOL_TIMEOUT=300000 for a 240s SubMCP timeout. Other clients have an equivalent setting; give it headroom over SUBMCP_TIMEOUT, never less.

Tools

delegate

One sub-agent, one report.

param	type	default	meaning
task	string	required	Self-contained instructions, including the output format you want.
profile	string	general	general, researcher, coder, reviewer.
files	string[]	null	Paths handed over up front so the sub-agent doesn't hunt.
write	bool	false	Allow edits. Ignored unless SUBMCP_ALLOW_WRITE=1.
model	string	null	Override the NIM model for this run.
max_steps	int	null	Tool-call budget for this run (falls back to SUBMCP_MAX_STEPS).

Returns markdown: the report, then a footer with the model, step count, tool calls, and any files changed.

delegate_parallel

Several independent sub-agents at once, capped at SUBMCP_MAX_PARALLEL, sharing one connection.

param	type	default	meaning
tasks	string[]	required	One self-contained task string per sub-agent.
profile	string	general	Applies to all of them.
files	string[]	null	Handed to every sub-agent.
model	string	null	Override the NIM model.

Returns one document with a ## Task N section per input, in order. A task that fails gets a section marked FAILED with the reason; the others still come back. There is deliberately no write here — concurrent edits to one working tree is how you lose work.

list_agents

No parameters, no API key needed. Reports the profiles, the model, the sandbox root, the budgets, and which capability gates are open. Use it as a setup check.

Writing a good task

The sub-agent starts cold. It cannot see your conversation, your open files, the user's last message, or anything you already worked out. Everything it needs goes in the string.

Good: "Find every call site of load_config under submcp/ and list each as path:line with one line on how the result is used. Answer as a markdown list."

Bad: "look into that config thing"

Say what to look at, what to produce, and what "done" means.

Profiles

profile	for
general	Default. One bounded task, fewest tool calls that actually settle it, reports what's true rather than what's likely.
researcher	Tracing how something really works — entry points, call paths, data flow, config. Never answers from a filename or a guess. Modifies nothing.
coder	The smallest change that satisfies the task, matching the style already in the file. Never invents an API it hasn't seen.
reviewer	Correctness bugs, unhandled failure paths, security holes, convention violations — worst first, each with the exact line. Reports; doesn't rewrite.

Environment variables

Every knob is an env var, so the whole server is tunable from your client's env block without touching code. See .env.example.

variable	default	meaning
NVIDIA_API_KEY	(required)	Your NIM key. Without it the server still starts; list_agents works and delegate returns setup instructions.
SUBMCP_MODEL	stepfun-ai/step-3.7-flash	Model for sub-agents.
SUBMCP_BASE_URL	https://integrate.api.nvidia.com/v1	OpenAI-compatible endpoint. Point it at a self-hosted NIM if you have one.
SUBMCP_ROOT	server cwd	Sandbox root. Every sub-agent file operation is confined here.
SUBMCP_MAX_STEPS	12	Tool-call budget per delegation.
SUBMCP_TIMEOUT	240	Wall-clock ceiling per delegation, seconds.
SUBMCP_MAX_PARALLEL	4	Concurrency cap for delegate_parallel.
SUBMCP_MAX_OUTPUT_CHARS	20000	Truncation limit on any single tool result fed back to the sub-agent.
SUBMCP_TEMPERATURE	0.2	Sampling temperature.
SUBMCP_TOP_P	0.95	Nucleus sampling.
SUBMCP_MAX_TOKENS	4096	Max tokens per NIM completion.
SUBMCP_THINKING	0	step-3.7-flash reasons by default; off is faster and cheaper for delegated grunt work.
SUBMCP_ALLOW_WRITE	0	Global kill switch for file edits. Off.
SUBMCP_ALLOW_SHELL	0	Global kill switch for shell commands. Off.

Booleans accept 1, true, yes, on.

Security model

Sandbox root. Every sub-agent file operation resolves under SUBMCP_ROOT (default: the server's working directory). Escapes via .., absolute paths, and symlinks are rejected after Path.resolve(), not before — a symlink pointing out of the tree is refused.

Secret denylist. Refused by exact filename (.env, .env.local, id_rsa, id_ed25519, credentials, .npmrc, .pypirc, .netrc) and by suffix (.pem, .key, .pfx, .p12), for reads and writes. .env.example stays readable.

Two gates, both off by default.

• SUBMCP_ALLOW_WRITE=0 — sub-agents get no write_file/edit_file tools at all. delegate(write=True) is ignored while this is off; the gate is the operator's, not the model's.
• SUBMCP_ALLOW_SHELL=0 — no run tool. Turning this on lets a sub-agent execute arbitrary commands in the sandbox root. Only do that in a repo you'd let a stranger run a script in.

With both off, the worst a sub-agent can do is read non-secret files inside one directory and tell you about them.

Key handling. Your API key never leaves the server process. Every string headed back to the host — reports, tool results, error messages, HTTP failures — goes through a redaction pass first.

When NOT to delegate

Delegation costs a cold start and a NIM round trip. It's a loss when:

• It's one file and you know which one. Just read it. Delegating a single Read is slower and worse.
• The task depends on this conversation. The sub-agent can't see it. If explaining the context takes longer than doing the work, do the work.
• It's a judgement call the user is waiting on. Architecture decisions, ambiguous requirements, anything where the answer is "it depends" — that's your job, not a sub-agent's.
• The subtasks are sequential. delegate_parallel is for independent work. Chained steps need delegate one at a time, or just do them yourself.
• You need the intermediate detail. You get the report, not the files it read. If you need the actual code in your context to edit it next, read it yourself.

Delegate when the work is bulky and separable: many files, mechanical, and the answer compresses to a paragraph.

Development

& ".venv\Scripts\python.exe" -m pytest -q

.venv\Scripts\python.exe -m submcp starts the server on stdio; it will sit there waiting for JSON-RPC on stdin, which is what a client does to it.

Layout

file	what
submcp/config.py	Env-driven Config, load_config(), redaction.
submcp/sandbox.py	Path resolution, escape checks, secret denylist, truncation.
submcp/tools.py	The tools a sub-agent gets, and their execution.
submcp/nim.py	NVIDIA NIM chat client — retries, redaction, injectable transport.
submcp/prompts.py	Profile personas and the composed sub-agent system prompt.
submcp/agent.py	The agent loop: chat → tool calls → repeat → report.
submcp/server.py	The MCP surface: delegate, delegate_parallel, list_agents.
.claude-plugin/plugin.json	Claude Code plugin manifest — MCP server wiring and the nvidia_api_key prompt.
skills/submcp/SKILL.md	Skill teaching an assistant when and how to call these tools.