Skip to main content
Glama
Animuni-Express

SubMCP

by Animuni-Express
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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.

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.

Available Tools

3 tools
delegateA

Run a bounded sub-agent on the user's NVIDIA NIM account and return its written report.

Reach for this to keep large, mechanical, or exploratory work out of your own context: tracing how a feature flows across many files, auditing a directory for a pattern, summarising an unfamiliar module or dependency, drafting a migration plan, reviewing a diff. The sub-agent reads the repository itself and spends NIM tokens doing it; you only receive the finished report.

task must stand on its own. The sub-agent cannot see this conversation, your open files, the user's last message, or anything you have already worked out - it starts cold at the repo root. Spell out what to look at, what to produce, and what "done" means. 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 we discussed".

Parameters: task - self-contained instructions, including the output format you want back. profile - "general" (default), "researcher", "coder", or "reviewer". Researcher for read-and-explain sweeps, coder for focused edits, reviewer for critique. files - paths to hand over up front so the sub-agent doesn't waste steps hunting. write - allow file edits. Off by default, and ignored entirely unless the server was started with SUBMCP_ALLOW_WRITE=1. Leave it off for investigation. model - override the NIM model for this run (default stepfun-ai/step-3.7-flash). max_steps - tool-call budget for this run (default 12).

Returns a markdown report: the sub-agent's findings, plus the model used, how many steps it took, which tools it called, and any files it changed. The sub-agent is sandboxed to the server's root directory, is read-only unless write=True, cannot run shell commands unless the operator enabled SUBMCP_ALLOW_SHELL, and refuses to read secrets (.env, private keys, credentials files).

For several independent subtasks, call delegate_parallel once instead of calling this tool repeatedly - it runs them concurrently over one connection.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYes
filesNo
modelNo
writeNo
profileNogeneral
max_stepsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully bears the burden of behavioral disclosure. It details that the sub-agent starts cold with no conversation context, is sandboxed to the root, is read-only unless `write=True`, requires SUBMCP_ALLOW_WRITE for write to take effect, cannot run shell commands without SUBMCP_ALLOW_SHELL, and refuses to read secrets. It also explains the return format and steps taken. This is comprehensive and adds far beyond any annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with clear sections: purpose, usage, task requirements, parameter list, return value, and safety constraints. Every sentence adds valuable information, from examples of good and bad tasks to the explicit mention of the parallel sibling. It is dense and efficient despite its length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, sub-agent execution, environment-dependent behavior, permissions, and sandboxing), the description covers all essential aspects: when to use, how to construct the task, parameter nuances, return value, safety/read-only guarantees, and pointer to the parallel variant. The output schema is optionally present, but the description even describes the markdown report contents, so no gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate, and it does. Each parameter is explained with its purpose, default, and guidance (e.g., `profile` options with what each is for, `files` as upfront path hints, `write` with environment caveat, `model` with default, `max_steps` as tool-call budget). The `task` parameter also includes a good/bad example, adding rich semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Run a bounded sub-agent on the user's NVIDIA NIM account and return its written report.' This clearly identifies what the tool does and its output. It further distinguishes itself from the sibling `delegate_parallel` by specifying it is for a single delegation, not parallel subtasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is explicit: 'Reach for this to keep large, mechanical, or exploratory work out of your own context' followed by concrete example use cases. It also provides an exclusion: 'For several independent subtasks, call `delegate_parallel` once instead.' This tells agents exactly when to use this tool vs. alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delegate_parallelA

Run several independent sub-agents at once and return every report in one answer.

This is the tool to use whenever the work splits into pieces that do not depend on each other: "summarise each of these four modules", "check these three services for the same misconfiguration", "for each failing test, find the cause". Running them concurrently on one NIM connection is much faster than calling delegate in a loop, and all the reading still happens outside your context.

Every string in tasks is a separate cold-start sub-agent with no memory of the others and no view of this conversation. Do not chain them - task 2 cannot use task 1's answer. If the work is genuinely sequential, use delegate one step at a time. Each task string must be self-contained and say what output you want, exactly as for delegate.

Parameters: tasks - list of self-contained task strings, one sub-agent each. profile - "general" (default), "researcher", "coder", or "reviewer"; applies to all. files - paths handed to every sub-agent up front. model - override the NIM model (default stepfun-ai/step-3.7-flash).

Concurrency is capped at SUBMCP_MAX_PARALLEL (default 4); extra tasks queue. All sub-agents are read-only here - there is no write parameter, because concurrent edits to one working tree are how you lose work. Use delegate with write=True for edits.

Returns one markdown document with a ## Task N section per input task, in the order you supplied them. A task that fails gets its own section marked FAILED with the reason; the other reports still come back intact, so one bad task never costs you the rest.

ParametersJSON Schema
NameRequiredDescriptionDefault
filesNo
modelNo
tasksYes
profileNogeneral

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It discloses that each task is a cold-start sub-agent with no memory, that concurrency is capped at SUBMCP_MAX_PARALLEL, that sub-agents are read-only with no `write` parameter, and that failures are isolated into a FAILED section without losing other results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a clear first line, usage conditions, parameter breakdown, and return behavior. Despite being detailed, every sentence adds critical information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of parallel sub-agents, the description covers use cases, restrictions, parameters, return format, failure handling, and the relationship to the sibling `delegate` tool. No crucial behavioral aspect is left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema has 0% description coverage, the description includes a parameter list that explains each argument: self-contained tasks, profile options, files given to every sub-agent, and model override. This compensates fully for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it runs several independent sub-agents concurrently and returns all reports in one answer. Explicitly distinguishes from the sibling `delegate` by noting it is for splitting work into independent pieces, making it unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use with examples, explicitly discourages chaining tasks, and directs users to `delegate` for sequential work and for edits (with write=True). Also specifies that each task must be self-contained.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_agentsA

Show what SubMCP can do right now: profiles, model, sandbox root, and capability gates.

Call this before your first delegate in a session, or when a delegation behaves unexpectedly - it tells you which directory sub-agents are confined to, whether writes and shell are enabled, and what the step and timeout budgets are. Needs no API key, so it also works as a setup check: it will say plainly if NVIDIA_API_KEY is missing.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully carries the transparency burden. It discloses the tool's read-only nature, the specific information returned (directory confinement, write/shell enablement, step and timeout budgets), and its behavior when NVIDIA_API_KEY is missing. This is rich behavioral detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact yet comprehensive, with each sentence earning its place. The first sentence states purpose, the second gives usage context and behaviors, and the third adds the API-key check nuance. It is front-loaded and free of redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's simplicity, the description covers purpose, usage timing, output expectations, and edge-case behavior (missing API key). Since an output schema exists, the description need not detail return values, and it sufficiently covers the operational context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description appropriately avoids inventing parameter semantics and instead clarifies what the tool outputs, which is consistent with a no-argument introspection tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Show what SubMCP can do right now: profiles, model, sandbox root, and capability gates,' which clearly identifies the tool's purpose as an informational listing. It distinguishes from sibling delegate tools by focusing on capability introspection rather than execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided: 'Call this before your first delegate in a session, or when a delegation behaves unexpectedly.' This gives clear when-to-use context, and the note about needing no API key frames it as a setup check, effectively differentiating from delegation alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A5/5.0
Disambiguation5/5

Each tool has a clearly distinct role: delegate runs one sub-agent, delegate_parallel runs multiple independent ones concurrently, and list_agents inspects capabilities. The descriptions explicitly delineate when to use each, with delegate_parallel contrasted against delegate for independent vs. sequential work, leaving no ambiguity.

Naming Consistency5/5

All tool names follow a consistent snake_case verb-based pattern: delegate, delegate_parallel, list_agents. The shared 'delegate' prefix in the first two creates an obvious family, and list_agents follows a verb_noun structure, making the naming predictable and readable.

Tool Count5/5

Three tools is a well-scoped count for a sub-agent delegation server. Each tool covers a necessary function—single execution, parallel execution, and environment introspection—without redundancy or missing core operations.

Completeness5/5

The tool surface fully covers the delegation workflow: run one task, run several tasks concurrently, and check the server's current capabilities and limits. No obvious gaps exist; the delegate and delegate_parallel return final reports directly, making the workflow self-contained.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Animuni-Express/SubMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server