Servidores MCP en Claude Code y en el agente: alcance, credenciales y recursos

MCP (Model Context Protocol) es el estándar para conectar un agente con sistemas externos: un servidor MCP expone herramientas (acciones) y recursos (contenido). En Claude Code y en el Agent SDK, las preguntas del examen giran alrededor de cuatro decisiones: dónde va cada servidor, cómo viajan las credenciales, qué ve el agente cuando hay varios y qué conviene exponer como recurso.

Dónde va cada servidor

Alcance	Archivo	Quién lo recibe
Alcance de proyecto (project scope)	.mcp.json en la raíz del repo	Todo el equipo, por git
Alcance de usuario (user scope)	~/.claude.json	Solo vos, en todos tus proyectos

Lo del equipo (el servidor de Jira, el de la base de staging) va en .mcp.json. Un servidor personal o experimental va en ~/.claude.json: queda disponible en todos tus proyectos y no toca a nadie más. Ponerlo en .mcp.json se lo impondría al equipo. (Claude Code tiene además un alcance local, también guardado en ~/.claude.json, para un servidor tuyo en un solo proyecto.)

Por seguridad, Claude Code pide aprobación en una sesión interactiva antes de usar los servidores de un .mcp.json que llegó con el repo.

Los secretos nunca van escritos

Un token escrito tal cual en .mcp.json entra al historial de git y lo lee cualquiera con acceso, aunque después se borre. La solución es la expansión de variables de entorno (environment variable expansion):

{
  "mcpServers": {
    "github": {
      "command": "github-mcp",
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

El archivo se comparte; el valor queda en la máquina de cada desarrollador. También existe ${VAR:-valor} para dar un valor por defecto. Si el secreto ya se commiteó, además hay que rotarlo.

Varios servidores a la vez

Las herramientas de todos los servidores configurados, de proyecto y de usuario, se descubren al conectar y quedan disponibles a la vez. Los niveles se suman: el personal no tapa al del equipo y no hay que activar nada. Un agente puede usar jira (del proyecto) y notes (tuyo) en el mismo pedido.

Herramienta o recurso

Un recurso MCP (MCP resource) expone un catálogo de contenido: esquemas de base de datos, documentos de políticas, resúmenes de issues, la jerarquía de la documentación. El agente ve qué hay disponible sin gastar llamadas exploratorias. Si un agente hace cinco llamadas a list_tables y describe_table en cada conversación, o vuelve a leer los mismos seis documentos de políticas, eso es un recurso. Las tools son acciones; los resources, contenido.

Comunidad primero

Para una integración estándar (Jira, Slack, GitHub), primero se evalúa un servidor de la comunidad (community MCP server): está mantenido y cubre los casos comunes. Uno propio, chico y acotado, solo para el hueco real del equipo, como una acción de aprobación interna.

Si el agente ignora tu herramienta MCP

Si un search_codebase descrito como “Searches code” pierde contra Grep, la causa es la descripción: Grep llega con una descripción integrada detallada. Ampliá la de la herramienta MCP con qué devuelve y cuándo preferirla. El modelo no mide velocidad ni les da prioridad propia a las integradas.

Las trampas típicas

• Construir un servidor propio sin mirar los que ya existen.
• Llamar a la API por Bash y perder descripciones y respuestas estructuradas.
• Copiar el esquema o las políticas en el system prompt: cuesta tokens en cada pedido y queda desactualizado.
• Sacar Bash o forzar tool_choice para que use la herramienta MCP.

En el examen

“Para todo el equipo” es .mcp.json; “solo para mí, en todos mis proyectos” es ~/.claude.json; un token literal se cambia por ${VARIABLE}; llamadas exploratorias repetidas piden un recurso.