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

) 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 . 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 `` 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-... \
  -- "/.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": "\\.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": "\\.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 = "/.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

(`/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