SubMCP

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

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

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 burnsNIMtokens 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. Onedelegate_parallelcall, 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)

Claude Code prompts you once for your NVIDIA NIM API key (get one athttps://build.nvidia.com) and stores it securely (OS keychain, or~/.claude/.credentials.jsonwhere no keychain is available) — no plaintext.envneeded. The server runs viauvxstraight from this repo, so there's no local clone or venv to manage. Ask your assistant to calllist_agentsafter installing to confirm the key and sandbox are wired up.

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 athttps://build.nvidia.com. Then wire the server into your client (next section) and ask your assistant to calllist_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.

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

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

Check it withclaude mcp list, or/mcpinside a session.

.cursor/mcp.jsonin the project (or~/.cursor/mcp.jsonglobally) — same shape:

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

Then enablesubmcpunder Settings → MCP.

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

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

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

A delegation is a whole agent loop — up toSUBMCP_MAX_STEPSmodel calls. SubMCP's own ceiling isSUBMCP_TIMEOUT(240s default). If yourhostkills 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'sMCP_TOOL_TIMEOUT(milliseconds), set in the client environment, e.g.MCP_TOOL_TIMEOUT=300000for a 240s SubMCP timeout. Other clients have an equivalent setting; give it headroom overSUBMCP_TIMEOUT, never less.

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

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

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

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.

The sub-agent startscold. 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 ofload_configundersubmcp/and list each aspath:linewith 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.

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

Sandbox root.Every sub-agent file operation resolves underSUBMCP_ROOT(default: the server's working directory). Escapes via.., absolute paths, and symlinks are rejected afterPath.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 readsandwrites..env.examplestays readable.

- SUBMCP_ALLOW_WRITE=0— sub-agents get nowrite_file/edit_filetools 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— noruntool. 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.

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 singleReadis 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_parallelis for independent work. Chained steps needdelegateone 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 isbulky and separable: many files, mechanical, and the answer compresses to a paragraph.

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

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

An MCP server for AI video generation. MCP server for AI video generation. Lets Claude, ChatGPT, OpenClaw , Hermes & other agents create AI videos and publish them to YouTube, TikTok, Instagram etc..

HumanDesign.ai MCP is the official account-connected Human Design server for Claude, ChatGPT, Codex, Cursor, and VS Code.

A Model Context Protocol (MCP) server written in Go that wraps the APsystems OpenAPI, giving AI assistants like Claude direct access to your solar monitoring data. Includes an optional web dashboard for visual monitoring.

MCP server for interacting with the APVISO AI-powered penetration testing platform from Claude Code, Cursor, Windsurf, Codex, and other MCP-compatible tools.

AI-powered text-to-speech MCP server with instant voice cloning. Generate speech from Claude Desktop, Claude Code, or n8n using 5 built-in voices (English, German, French, Spanish) or clone any voice from a short audio sample. Runs fully local, no API keys, no cloud. Supports stdio, SSE, and HTTP transports.

Chess.com player, game, and daily-puzzle tools where each tool ships its own interactive React view — board replays and a playable puzzle widget, not just text. Built with Skybridge for ChatGPT & Claude.

Pre-indexed code knowledge graph, auto syncs on code changes, for Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro, and Hermes Agent — fewer tokens, fewer tool calls, 100% local

Live crypto technical analysis MCP server — EMA, RSI, MACD, ATR, Bollinger Bands, TSS scoring, and Claude AI bull/bear debate via CoinGecko free API

A high-performance trading system for Claude Desktop, providing real-time market data via Tiingo and optional Telegram alerts.

Ask Power BI in plain English, from Claude — charts + full ETL context.