SubMCP

SubMCP

Un servidor MCP que le da a Claude Code, Cursor, Codex, Windsurf o Zed la capacidad de delegar subtareas acotadas a sub-agentes que se ejecutan en tu propia cuenta de NVIDIA NIM.

Modelo predeterminado: stepfun-ai/step-3.7-flash.

Por qué

Dos razones, ambas sobre tu ventana de contexto.

Descarga de contexto. «Rastrear cómo fluye la autenticación a través de este servicio» cuesta veinte lecturas de archivos. Hazlo en tu sesión principal y esos veinte archivos permanecen en tu contexto durante el resto de la conversación. Delégalo y el sub-agente quema tokens NIM leyéndolos — recibes un informe. La parte costosa ocurre en otro lugar, en un modelo por el que pagas a NVIDIA, y el contexto de tu asistente se mantiene limpio para el trabajo que realmente lo necesita.

Expansión en paralelo. Cuatro preguntas independientes se convierten en cuatro sub-agentes ejecutándose a la vez en una sola conexión, en lugar de cuatro viajes de ida y vuelta secuenciales a través de tu modelo principal. Una llamada a delegate_parallel, una respuesta, con todos los informes dentro.

Los sub-agentes son de solo lectura y están en un sandbox por defecto. Tú decides si permites escrituras y shell.

Inicio rápido — plugin de Claude Code (recomendado)

/plugin install Animuni-Express/submcp

Claude Code te pedirá una vez tu clave de API de NVIDIA NIM (obtén una en https://build.nvidia.com) y la almacena de forma segura (llavero del sistema operativo, o ~/.claude/.credentials.json donde no haya llavero disponible) — no se necesita .env en texto plano. El servidor se ejecuta mediante uvx directamente desde este repositorio, así que no hay clon local ni venv que gestionar. Pide a tu asistente que llame a list_agents después de instalar para confirmar que la clave y el sandbox están configurados.

Todo lo siguiente es para configuración manual: otros clientes MCP (Cursor, Codex, Windsurf, Zed), o ejecutar desde un clon local en lugar del plugin.

Inicio rápido — clon manual

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

Obtén una clave en https://build.nvidia.com. Luego conecta el servidor a tu cliente (siguiente sección) y pide a tu asistente que llame a list_agents — no necesita clave de API y te dirá de inmediato si la clave, la raíz del sandbox y las compuertas son lo que esperas.

Configuración del cliente MCP

Cada ejemplo ejecuta el intérprete de venv directamente. No uses un python simple — el cliente no tendrá tu venv activado, y submcp no será importable.

Reemplaza <path-to-submcp> con la ruta absoluta a tu propio clon. Las rutas de Windows en JSON necesitan barras invertidas dobles.

Claude Code

CLI (ámbito de proyecto — escribe .mcp.json por ti):

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

Usa --scope user en su lugar para que esté disponible en todos los proyectos.

O escribe .mcp.json en la raíz del repositorio manualmente:

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

Compruébalo con claude mcp list, o /mcp dentro de una sesión.

Cursor

.cursor/mcp.json en el proyecto (o ~/.cursor/mcp.json globalmente) — misma forma:

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

Luego habilita submcp en Configuración → MCP.

Codex

~/.codex/config.toml — TOML, y la tabla es mcp_servers (guion bajo):

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

[mcp_servers.submcp.env]
NVIDIA_API_KEY = "nvapi-..."

Windsurf / Zed / cualquier otro

Cualquier cliente que hable stdio MCP acepta las mismas tres cosas: el comando (<venv>/Scripts/python.exe), los argumentos (["-m", "submcp"]) y un bloque env con NVIDIA_API_KEY.

Tiempos de espera

Una delegación es un bucle completo de agente — hasta SUBMCP_MAX_STEPS llamadas al modelo. El propio límite de SubMCP es SUBMCP_TIMEOUT (240s por defecto). Si tu host mata la llamada a la herramienta primero, pierdes el informe aunque el sub-agente haya terminado, así que eleva el límite del host por encima del de SubMCP. En Claude Code eso es MCP_TOOL_TIMEOUT (milisegundos), configurado en el entorno del cliente, p. ej. MCP_TOOL_TIMEOUT=300000 para un tiempo de espera de SubMCP de 240s. Otros clientes tienen un ajuste equivalente; dale margen sobre SUBMCP_TIMEOUT, nunca menos.

Herramientas

delegate

Un sub-agente, un informe.

parámetro	tipo	predeterminado	significado
task	string	obligatorio	Instrucciones autocontenidas, incluido el formato de salida que quieras.
profile	string	general	general, researcher, coder, reviewer.
files	string[]	null	Rutas entregadas de antemano para que el sub-agente no tenga que buscar.
write	bool	false	Permitir ediciones. Se ignora a menos que SUBMCP_ALLOW_WRITE=1.
model	string	null	Sobrescribir el modelo NIM para esta ejecución.
max_steps	int	null	Presupuesto de llamadas a herramientas para esta ejecución (recurre a SUBMCP_MAX_STEPS).

Devuelve markdown: el informe, luego un pie de página con el modelo, el número de pasos, las llamadas a herramientas y cualquier archivo modificado.

delegate_parallel

Varios sub-agentes independientes a la vez, con un máximo de SUBMCP_MAX_PARALLEL, compartiendo una conexión.

parámetro	tipo	predeterminado	significado
tasks	string[]	obligatorio	Una cadena de tarea autocontenida por sub-agente.
profile	string	general	Se aplica a todos.
files	string[]	null	Se entrega a cada sub-agente.
model	string	null	Sobrescribir el modelo NIM.

Devuelve un documento con una sección ## Task N por entrada, en orden. Una tarea que falla recibe una sección marcada como FAILED con el motivo; las demás siguen llegando. Deliberadamente no hay write aquí — las ediciones concurrentes en un mismo árbol de trabajo es como se pierde trabajo.

list_agents

Sin parámetros, no necesita clave de API. Informa sobre los perfiles, el modelo, la raíz del sandbox, los presupuestos y qué compuertas de capacidad están abiertas. Úsalo como verificación de configuración.

Cómo escribir un buen task

El sub-agente comienza en frío. No puede ver tu conversación, tus archivos abiertos, el último mensaje del usuario ni nada de lo que ya hayas resuelto. Todo lo que necesita va en la cadena.

Bueno: «Encuentra cada punto de llamada de load_config bajo submcp/ y lista cada uno como path:line con una línea sobre cómo se usa el resultado. Responde como una lista de markdown.»

Malo: «mira eso de la configuración»

Di qué mirar, qué producir y qué significa «hecho».

Perfiles

perfil	para
general	Predeterminado. Una tarea acotada, la menor cantidad de llamadas a herramientas que realmente la resuelven, informa lo que es verdadero en lugar de lo que es probable.
researcher	Rastrear cómo funciona realmente algo — puntos de entrada, rutas de llamada, flujo de datos, configuración. Nunca responde a partir de un nombre de archivo o una suposición. No modifica nada.
coder	El cambio más pequeño que satisface la tarea, siguiendo el estilo ya presente en el archivo. Nunca inventa una API que no ha visto.
reviewer	Errores de corrección, rutas de fallo no manejadas, agujeros de seguridad, violaciones de convenciones — primero los peores, cada uno con la línea exacta. Informa; no reescribe.

Variables de entorno

Cada perilla es una variable de entorno, así que todo el servidor se puede ajustar desde el bloque env de tu cliente sin tocar código. Ver .env.example.

variable	predeterminado	significado
NVIDIA_API_KEY	(obligatorio)	Tu clave NIM. Sin ella el servidor igual arranca; list_agents funciona y delegate devuelve instrucciones de configuración.
SUBMCP_MODEL	stepfun-ai/step-3.7-flash	Modelo para sub-agentes.
SUBMCP_BASE_URL	https://integrate.api.nvidia.com/v1	Endpoint compatible con OpenAI. Apúntalo a un NIM autoalojado si tienes uno.
SUBMCP_ROOT	server cwd	Raíz del sandbox. Toda operación de archivos de sub-agentes se limita aquí.
SUBMCP_MAX_STEPS	12	Presupuesto de llamadas a herramientas por delegación.
SUBMCP_TIMEOUT	240	Límite de tiempo real por delegación, en segundos.
SUBMCP_MAX_PARALLEL	4	Límite de concurrencia para delegate_parallel.
SUBMCP_MAX_OUTPUT_CHARS	20000	Límite de truncamiento en cualquier resultado de herramienta individual devuelto al sub-agente.
SUBMCP_TEMPERATURE	0.2	Temperatura de muestreo.
SUBMCP_TOP_P	0.95	Muestreo de núcleo.
SUBMCP_MAX_TOKENS	4096	Máximo de tokens por finalización de NIM.
SUBMCP_THINKING	0	step-3.7-flash razona por defecto; desactivado es más rápido y barato para trabajo pesado delegado.
SUBMCP_ALLOW_WRITE	0	Interruptor global de apagado para ediciones de archivos. Apagado.
SUBMCP_ALLOW_SHELL	0	Interruptor global de apagado para comandos de shell. Apagado.

Los booleanos aceptan 1, true, yes, on.

Modelo de seguridad

Raíz del sandbox. Toda operación de archivos de sub-agentes se resuelve bajo SUBMCP_ROOT (predeterminado: el directorio de trabajo del servidor). Los escapes mediante .., rutas absolutas y enlaces simbólicos se rechazan después de Path.resolve(), no antes — un enlace simbólico que apunte fuera del árbol se rechaza.

Lista negra de secretos. Rechazados por nombre de archivo exacto (.env, .env.local, id_rsa, id_ed25519, credentials, .npmrc, .pypirc, .netrc) y por sufijo (.pem, .key, .pfx, .p12), para lecturas y escrituras. .env.example sigue siendo legible.

Dos compuertas, ambas apagadas por defecto.

• SUBMCP_ALLOW_WRITE=0 — los sub-agentes no reciben herramientas write_file/edit_file en absoluto. delegate(write=True) se ignora mientras esto esté apagado; la compuerta es del operador, no del modelo.
• SUBMCP_ALLOW_SHELL=0 — sin herramienta run. Activar esto permite que un sub-agente ejecute comandos arbitrarios en la raíz del sandbox. Solo hazlo en un repositorio en el que dejarías que un extraño ejecutara un script.

Con ambas apagadas, lo peor que puede hacer un sub-agente es leer archivos no secretos dentro de un directorio y contarte sobre ellos.

Manejo de claves. Tu clave de API nunca sale del proceso del servidor. Cada cadena que regresa al host — informes, resultados de herramientas, mensajes de error, fallos HTTP — pasa primero por un proceso de redacción.

Cuándo NO delegar

Delegar cuesta un arranque en frío y un viaje de ida y vuelta a NIM. Es una pérdida cuando:

• Es un solo archivo y sabes cuál. Solo léelo. Delegar un único Read es más lento y peor.
• La tarea depende de esta conversación. El sub-agente no puede verla. Si explicar el contexto tarda más que hacer el trabajo, haz el trabajo.
• Es una decisión de criterio que el usuario está esperando. Decisiones de arquitectura, requisitos ambiguos, cualquier cosa donde la respuesta sea «depende» — eso es tu trabajo, no el de un sub-agente.
• Las subtareas son secuenciales. delegate_parallel es para trabajo independiente. Los pasos encadenados necesitan delegate uno a la vez, o simplemente hazlos tú mismo.
• Necesitas el detalle intermedio. Recibes el informe, no los archivos que leyó. Si necesitas el código real en tu contexto para editarlo después, léelo tú mismo.

Delega cuando el trabajo sea voluminoso y separable: muchos archivos, mecánico, y la respuesta se comprime en un párrafo.

Desarrollo

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

.venv\Scripts\python.exe -m submcp inicia el servidor en stdio; se quedará esperando JSON-RPC en stdin, que es lo que un cliente le hace.

Estructura

archivo	qué
submcp/config.py	Impulsado por entorno Config, load_config(), redacción.
submcp/sandbox.py	Resolución de rutas, comprobaciones de escape, lista negra de secretos, truncamiento.
submcp/tools.py	Las herramientas que recibe un sub-agente y su ejecución.
submcp/nim.py	Cliente de chat NVIDIA NIM — reintentos, redacción, transporte inyectable.
submcp/prompts.py	Personas de perfil y el prompt de sistema compuesto del sub-agente.
submcp/agent.py	El bucle del agente: chat → llamadas a herramientas → repetir → informe.
submcp/server.py	La superficie MCP: delegate, delegate_parallel, list_agents.
.claude-plugin/plugin.json	Manifiesto del plugin de Claude Code — cableado del servidor MCP y el prompt nvidia_api_key.
skills/submcp/SKILL.md	Habilidad que enseña a un asistente cuándo y cómo llamar a estas herramientas.