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.

Related MCP server: Claude Team MCP

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.

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.

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

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.

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