# 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

```bash
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):

```bash
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:

```json
{
  "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:

```json
{
  "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):

```toml
[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

```powershell
& ".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. |