Servidores MCP

Conecta servidores MCP locales o remotos para dar a los agentes más herramientas e información.

Inspecciona los servidores conectados

Escribe /extensions y pulsa c para abrir el navegador MCP de solo lectura.

1. Selecciona un servidor y pulsa Intro para consultar sus herramientas y prompts.
2. Selecciona una herramienta para ver su esquema de entrada.
3. Selecciona un prompt y pulsa i para invocarlo.
4. Pulsa r para actualizar la conexión o e para ver el archivo y la entrada de ajustes que debes editar.

Pasos 1 y 4. Consulta la identidad y el estado, actualiza o abre los ajustes correspondientes.

El navegador distingue servidores conectados, declarados, desconectados e indisponibles; es la forma más rápida de comprobar si una configuración está activa.

Pasos 2 y 3. Inspecciona los esquemas en el navegador y comprueba con una ejecución que la herramienta funciona.

Configura servidores

Añade un mapa mcpServers a ~/.clarvis/settings.json para servidores personales o a .clarvis/settings.json para los del proyecto. Cada clave del mapa será el nombre del servidor:

{
  "mcpServers": {
    "workspace-tools": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "tooling/local-mcp.ts"],
      "env": {
        "SERVICE_TOKEN": "${SERVICE_TOKEN}"
      },
      "resources": true
    },
    "remote-docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

Sustituye el comando y la URL del ejemplo por servidores que controles. Guarda las credenciales en variables de entorno: las referencias ${NAME} se resuelven al conectar, sin guardar secretos en settings.json.

Elige el transporte

• stdio exige command. Admite args, env, env_vars, cwd, shared y resources; no admite url, headers ni credenciales remotas.
• http y sse exigen una URL válida http:// o https://. Admiten headers y resources, pero no command, args, env ni shared.
• Si omites type, se usa stdio.

Todos admiten startup_timeout_sec, tool_timeout_sec, enabled, required, enabled_tools y disabled_tools. Las listas de herramientas permitidas y denegadas no pueden solaparse. env_vars de stdio reenvía solo las variables del anfitrión indicadas, además del mapa explícito env. Un servidor remoto puede usar bearer_token_env_var y relacionar cabeceras HTTP con nombres de variables mediante env_http_headers, para no guardar credenciales en los ajustes. expandVariables es true por defecto; desactívalo solo si otro formato de paquete ya se encarga de expandir los marcadores.

Usa shared: true solo si un proceso stdio persistente puede atender ejecuciones solapadas con seguridad. Una conexión compartida no admite preguntas MCP al operador; no la uses si el servidor se autentica de ese modo.

Los recursos están activados por defecto. Si el servidor los anuncia, Clarvis añade <server>.list_resources y <server>.read_resource. Usa resources: false para omitirlos.

Autoriza un servidor remoto

Si un servidor HTTP o SSE solicita OAuth, la CLI local interactiva y el modo local --print abren la página de autorización en tu navegador por defecto. Puede ocurrir al conectar, descubrir herramientas o recursos, o en una petición posterior. Clarvis solo acepta endpoints y redirecciones HTTPS —o HTTP en loopback—, comprueba un estado de un solo uso, intercambia el código con PKCE, valida el emisor si el servidor lo proporciona y reintenta una vez la operación rechazada.

La TUI no mantiene una ejecución del modelo esperando la autorización. El servidor queda inactivo en esa ejecución y Clarvis muestra una vez el motivo sin datos sensibles como aviso temporal, sin añadirlo al historial. Si no completas el navegador, puedes seguir escribiendo y ejecutando tareas. Al completar la autorización, se guarda el token para una ejecución posterior. Reconecta o empieza otra tarea después.

Las cabeceras del servidor MCP solo se usan en peticiones de recursos al origen configurado. Las peticiones de descubrimiento OAuth, registro y tokens no las heredan, aunque compartan origen. Las credenciales obtenidas mediante OAuth tienen prioridad.

Los registros y tokens se guardan fuera de los ajustes, en ~/.clarvis/state/mcp-oauth.json, aislados por espacio de trabajo, propietario y URL canónica. Clarvis crea el archivo con permisos privados donde el sistema lo permite y no incluye su contenido en prompts, trazas ni registros. Un kernel remoto o sin interfaz no puede abrir el navegador y falla explícitamente si necesita autorización interactiva; configura una credencial explícita en cabeceras para ese anfitrión.

Las opciones avanzadas están en oauth. client_id usa un cliente público previamente registrado. Una client_metadata_url HTTPS permite descubrir un Client ID Metadata Document. En otro caso se utiliza registro dinámico si el servidor lo admite. callback_url debe ser HTTPS o HTTP de loopback, tener una ruta distinta de la raíz y no contener consulta ni fragmento. callback_port elige el puerto de escucha local. Un identificador de cliente configurado tiene prioridad sobre el descubrimiento de metadatos y el registro dinámico.

Referencia un servidor desde un agente

La identidad estable para ajustes y hooks es <server>.<tool>. Por ejemplo, search de remote-docs siempre puede resolverse como remote-docs.search. Si el nombre local es único, válido y no choca con una herramienta integrada, Clarvis puede mostrarlo abreviado al modelo. Los nombres duplicados, inválidos o reservados reciben una alternativa determinista con espacio de nombres. La identidad con puntos sigue siendo la canónica.

Los servidores de plugins reciben el espacio de nombres del plugin:

quality-kit:checks.lint

Aquí quality-kit es el plugin, checks el servidor y lint la herramienta. Usa el nombre completo en las listas del agente y en los patrones de hooks.

Se aplica la confianza del espacio de trabajo

Un repositorio sin aprobar puede declarar servidores MCP, pero Clarvis no los inicia ni conecta. Al entrar solicita la huella protegida exacta; usa /workspace-trust para revisar, aprobar o revocar después. La aprobación corresponde al espacio, no a cada servidor.

Consulta también

• Hooks
• Plugins
• Referencia de extensiones