deepseek-subagent-mcp

Permite que Claude Code, Codex o cualquier otro cliente MCP tenga un agente DeepSeek Harness al que delegar trabajo, de la misma manera que delegaría a uno de sus propios subagentes.

MCP (Model Context Protocol) es el estándar mediante el cual un agente de codificación carga herramientas externas. DeepSeek Harness es el runtime de agente de código abierto de DeepSeek — un modelo en un bucle con herramientas de archivos y shell, lanzado en agosto de 2026 bajo licencia MIT. Este servidor se sitúa entre ellos: ejecuta un agente Harness en un proceso separado y expone seis herramientas para iniciarlo, supervisarlo, continuarlo y detenerlo.

El agente hijo tiene su propia ventana de contexto. Ese es el punto — le entregas una tarea autocontenida, consume sus propios tokens trabajando en los archivos, y recibes un resultado en lugar de una transcripción.

Requisitos

• Python 3.11 o más reciente

• Una clave de API de DeepSeek de platform.deepseek.com

• macOS 14+ en Apple Silicon, o Linux en x86-64 o arm64

No se necesita instalación de Node.js: el runtime Harness se distribuye como un ejecutable autocontenido dentro de la rueda deepseek-harness-sdk. Esa rueda es también el límite de plataforma — publica macosx_14_0_arm64, manylinux_2_28_x86_64 y manylinux_2_28_aarch64 y nada más, por lo que Windows, Macs con Intel y macOS 13 no pueden instalarlo en absoluto.

Instalar

uvx --from git+https://github.com/gaztrabisme/deepseek-subagent-mcp deepseek-subagent-mcp

Claude Code

Añade a .mcp.json en tu proyecto, o a ~/.claude.json para cada proyecto:

{
  "mcpServers": {
    "deepseek-subagent": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp",
        "deepseek-subagent-mcp"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "sk-...",
        "DSA_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Codex

Añade a ~/.codex/config.toml:

[mcp_servers.deepseek-subagent]
command = "uvx"
args = ["--from", "git+https://github.com/gaztrabisme/deepseek-subagent-mcp", "deepseek-subagent-mcp"]
env = { DEEPSEEK_API_KEY = "sk-...", DSA_WORKSPACE = "/path/to/your/project" }

Herramientas

Las ejecuciones son asíncronas por defecto porque una tarea de codificación puede llevar muchos minutos y los clientes MCP agotan el tiempo de espera de las llamadas a herramientas individuales. dsh_delegate regresa tan pronto como el trabajo está en cola; dsh_await realiza la espera e informa del progreso mientras lo hace. Para tareas cortas, pasa wait_seconds a dsh_delegate y omite la segunda llamada.

Cada dsh_delegate crea un agente, manteniendo un proceso de runtime y una sesión persistida. dsh_continue reingresa a esa sesión, por lo que el hijo aún tiene sus turnos anteriores en contexto.

Cada delegación indica cómo se verificará

dsh_delegate requiere un argumento verification: el comando que demuestra que la tarea está completa.

dsh_delegate(task="Fix the failing date parser", verification="pytest -q tests/test_dates.py")

El servidor ejecuta ese comando por sí mismo, en el espacio de trabajo del agente, después de que el hijo finalice. Que un hijo informe sus propios resultados de prueba es una afirmación; un código de salida es un hecho, y que los agentes declaren victoria prematuramente es un modo de fallo bien documentado.

El comando se clasifica mediante la misma política que controla las llamadas del propio hijo antes de ejecutarse — el llamante es otro agente y puede ser inyectado con indicaciones, por lo que "el llamante lo pidió" no es autorización. Pasa verification="true" cuando no hay nada que verificar genuinamente; una mentira explícita es mejor que un silencio por defecto.

Lo que se devuelve

Un subagente que devuelve su transcripción completa ha derrotado su propio propósito. Cuando la respuesta del hijo es mayor que DSA_SUMMARY_TOKENS, se le pide — en la misma sesión, como un turno adicional — que la reemplace con un resumen de transferencia en siete secciones: Objetivo, Restricciones y Preferencias, Progreso, Decisiones Clave, Próximos Pasos, Archivos Relevantes, Contexto Crítico. Eso es lo que cruza el límite de MCP.

Una respuesta que ya está por debajo del límite se devuelve textualmente y no cuesta un turno extra. La respuesta sin procesar siempre se conserva: dsh_transcript(run_id, raw=True).

Ejecución supervisada

Las llamadas a herramientas del hijo se controlan antes de ejecutarse. Un hook PreToolUse dentro del runtime entrega cada llamada propuesta a este servidor, que responde permitir o denegar; una llamada denegada regresa al modelo como un resultado de herramienta bloqueado que lleva la razón, y el modelo se adapta.

Un clasificador determinista decide primero, y decide la mayoría de las llamadas. Leer archivos, ls, grep, lecturas de control de versiones, ejecutar el código y las pruebas del propio espacio de trabajo están permitidos sin involucrar al modelo. Los comandos privilegiados, las eliminaciones fuera del espacio de trabajo, fetch-piped-into-a-shell y cualquier cosa que toque claves SSH o .env se deniegan directamente — incluso a través de un verbo de apariencia inofensiva, porque cat ~/.ssh/id_rsa es una herramienta de solo lectura aplicada a un secreto. Solo lo que el clasificador no puede clasificar escala.

La escalada se ejecuta en el mejor nivel que admite el cliente, resuelto al inicio e informado por dsh_list:

Cada nivel falla de forma segura. Un supervisor inalcanzable, un tiempo de espera, una solicitud mal formada o un cliente que no admite ninguna de las dos capacidades producen una denegación, nunca una aprobación.

La escalera se recorre en lugar de elegirse una vez: un nivel que da error cae al siguiente, por lo que un cliente que deja caer sampling — obsoleto en la revisión de la especificación del 2026-07-28, aún funcionando hoy — degrada a preguntarte en lugar de denegar todo. Un nivel que agota el tiempo no cae; una pregunta sin respuesta es un no, y volver a preguntar en otro canal solo duplicaría la espera.

Establece DSA_SUPERVISOR=off para deshabilitar la puerta por completo.

Lo que se muestra al supervisor son hechos estructurados, nunca la prosa del hijo: la herramienta, los programas en cada segmento de la tubería y cada ruta que el comando nombra con una bandera de dentro o fuera del espacio de trabajo. El hijo escribe tanto el comando como cualquier justificación para él, y un hijo que puede argumentar su propio caso lo hará. Una ruta que no se puede resolver estáticamente — $TMPDIR/out.txt — se informa como no resuelta en lugar de adivinarse, y cuenta como fuera.

examples/claude_supervisor.py ejecuta todo el patrón contra un Claude real, para clientes que no anuncian sampling por sí mismos:

DEEPSEEK_API_KEY=sk-... uv run python examples/claude_supervisor.py

Límites y costo

Un agente delegado gasta tu dinero en un bucle, por lo que cuatro límites independientes lo acotan, y cada ejecución informa lo que usó.

No hay cancelación a mitad de turno en el cable, por lo que cada parada es una muerte de proceso. Una muerte por un límite siempre tiene prioridad sobre lo que la propia ejecución informó: la salida de un proceso muerto nunca se lee como éxito.

dsh_delegate, dsh_await y dsh_list informan todos el uso de tokens — entrada, salida, lecturas y escrituras de caché, y número de pasos — sumados de lo que informó el proveedor. La entrada por paso se suma deliberadamente: cada solicitud factura todo el prefijo reenviado, por lo que el total es lo que realmente costó la delegación.

Configuración

Cada ajuste es una variable de entorno en el proceso del servidor.

Límites que debes conocer antes de confiar en esto

Estos provienen del protocolo de cable del SDK de Harness, no de decisiones tomadas aquí.

• El sandbox del sistema de archivos no cubre bash. dsh-fs-sandbox confina las herramientas write/edit del modelo al espacio de trabajo, pero dsh-bash-sandbox no está en el ejecutable de runtime empaquetado, por lo que bash en sí mismo no está confinado. El supervisor cubre esto: controla todas las herramientas, incluido bash, antes de la ejecución. Con DSA_SUPERVISOR=off no hay ningún límite en bash; apúntalo a una rama o a un directorio temporal.

• El sandbox solo restringe los efectos sobre archivos — no la red, procesos o llamadas al sistema. Y workspace-write permite /tmp además de la raíz del espacio de trabajo.

• Cancelar mata el proceso. No hay cancelación a mitad de turno en el cable, por lo que dsh_cancel termina el runtime. Las ediciones ya escritas permanecen en el disco y la sesión no se puede reanudar después.

• La sesión de un agente recolectado desaparece, pero sus resultados no. Después de DSA_IDLE_TIMEOUT, el proceso se libera; dsh_await y dsh_transcript aún funcionan en sus ejecuciones finalizadas, dsh_continue no.

• Las sesiones viven mientras dure el proceso. No hay cierre por sesión, por lo que la memoria crece con el historial de un agente. Cancela los agentes con los que hayas terminado.

• El upstream es una vista previa para desarrolladores. deepseek-harness-sdk está fijado en ==0.1.0rc7; dos candidatos de lanzamiento se enviaron en una semana. Espera que el cable se mueva.

Desarrollo

uv sync
uv run pytest                  # 127 tests, no API key, no network
uv run ruff check .
uv run deepseek-subagent-mcp   # starts on stdio; a client drives it

Las pruebas en vivo necesitan una clave real y consumen tokens; no son recogidas por pytest:

DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_task.py        # the product works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_result.py      # distillation and the archive
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_supervisor.py  # the gate works
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_escalation.py  # both escalation tiers
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_limits.py      # reaper and deadline
DEEPSEEK_API_KEY=sk-... uv run python tests/smoke_mcp.py         # all six tools

CLAUDE.md contiene la arquitectura y las restricciones del upstream; wiki/ contiene el registro de decisiones y lo que se midió.

Licencia

MIT.