Servidores MCP (Model Context Protocol)

MCP es el estándar abierto que Theus usa para conectar herramientas externas —bases de datos, APIs, sistemas de tickets, navegadores— como servidores que exponen tools, recursos y prompts a tu sesión.

Cuando conectas un servidor MCP, sus herramientas aparecen automáticamente en la sesión de Theus con el prefijo del servidor y el modelo puede invocarlas igual que las herramientas nativas. Esta página cubre el comando /mcp dentro de la TUI, los subcomandos de línea de comandos theus mcp …, el formato de configuración, los transportes soportados y los servidores internos que Theus monta por su cuenta (Ñaupa, computer-use y el contexto del proyecto).

El comando /mcp

Dentro de una sesión de Theus, /mcp abre el panel de gestión de servidores MCP, donde ves el estado de cada conexión (conectado, deshabilitado, error) y puedes reconectar o activar/desactivar servidores. Acepta estos argumentos directos:

/mcp                       # abre el panel de configuración de servidores
/mcp enable [server]       # habilita un servidor (o todos si omites el nombre)
/mcp disable [server]      # deshabilita un servidor (o todos)
/mcp reconnect <server>    # fuerza la reconexión de un servidor

Ejemplos:

/mcp enable            # habilita todos los servidores configurados
/mcp disable sentry    # deshabilita el servidor "sentry"
/mcp reconnect sentry  # reconecta el servidor "sentry"

Añadir y configurar servidores MCP

Desde tu terminal (fuera de la sesión interactiva) usa el grupo de subcomandos theus mcp para administrar servidores. El subcomando principal es add:

theus mcp add <name> <commandOrUrl> [args...]

Opciones de theus mcp add

Ejemplos reales

# Servidor HTTP:
theus mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Servidor HTTP con cabecera de autorización:
theus mcp add --transport http corridor https://app.corridor.dev/api/mcp --header "Authorization: Bearer ..."

# Servidor stdio con variables de entorno:
theus mcp add -e API_KEY=xxx my-server -- npx my-mcp-server

# Servidor stdio con flags del subproceso:
theus mcp add my-server -- my-command --some-flag arg1

Añadir con JSON

Para pegar una configuración completa (stdio o SSE) en formato JSON:

theus mcp add-json <name> '<json>' [--scope local|user|project]

Otros subcomandos theus mcp

Ámbitos de configuración

El ámbito (--scope) decide dónde se guarda la configuración y quién la ve:

Formato del archivo .mcp.json

Los servidores de ámbito project viven en un archivo .mcp.json en la raíz del repositorio, bajo la clave mcpServers. Cada entrada se identifica por su nombre y describe su transporte:

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["my-mcp-server"],
      "env": { "API_KEY": "${MY_API_KEY}" }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": { "Authorization": "Bearer ${SENTRY_TOKEN}" }
    }
  }
}

Servidores internos: los que Theus monta solo

Además de los servidores que configuras tú, Theus trae servidores MCP propios que se montan sin tocar .mcp.json ni theus mcp add:

Theus como servidor MCP: el contexto de tu proyecto

Además de consumir servidores MCP, Theus puede servir la inteligencia de tu proyecto por MCP. El comando theus --project-context-mcp arranca un servidor MCP por stdio que expone el índice del proyecto — el mismo grafo vivo, recall híbrido y memorias persistentes que usa el agente — a cualquier herramienta compatible con MCP.

Herramientas expuestas:

• recall — búsqueda híbrida sobre el proyecto: devuelve símbolos con archivo:línea, memorias relacionadas y el subgrafo de relaciones, sin gastar tokens leyendo código.
• symbols — símbolos del proyecto (funciones, clases, interfaces) con ubicación exacta; admite filtrar por archivo.
• project_map — resumen del proyecto: archivos indexados, conteo de símbolos, entidades principales y esquema de base de datos si existe.
• remember — persiste una decisión o aprendizaje como memoria del proyecto (sobrevive sesiones y es recuperable por recall).
• memories — lista las memorias guardadas del proyecto.

Registro en el .mcp.json del cliente (cualquier agente o editor MCP-compatible):

{
  "mcpServers": {
    "theus-context": {
      "command": "theus",
      "args": ["--project-context-mcp"]
    }
  }
}

Transportes soportados

• stdio — Theus lanza el servidor como subproceso local y se comunica por entrada/salida estándar. Requiere command, opcionalmente args y env. Es el transporte por defecto.
• http — Servidor remoto por HTTP (streamable). Requiere url; admite headers y OAuth.
• sse — Servidor remoto vía Server-Sent Events. Requiere url; admite headers y OAuth.

Autenticación OAuth

Los servidores HTTP y SSE pueden requerir OAuth. Pasa --client-id y usa --client-secret para que Theus te pida el secreto de forma segura (o léelo de la variable MCP_CLIENT_SECRET). Si el servidor exige un redirect URI pre-registrado, fija el puerto de callback con --callback-port. Las opciones de OAuth solo aplican a HTTP/SSE; para stdio se ignoran con un aviso.

Variables de entorno relacionadas

Flujo recomendado

1. Añade el servidor con theus mcp add … eligiendo el ámbito según quién debe verlo.
2. Verifica con theus mcp list y theus mcp get <name> en un directorio de confianza.
3. Dentro de la sesión, gestiona el estado con /mcp, /mcp enable, /mcp disable y /mcp reconnect.