Instalación de servidores MCP

Los servidores MCP se pueden configurar de tres formas diferentes según sus necesidades:

Opción 1: Agregar un servidor HTTP remoto

Los servidores HTTP son la opción recomendada para conectarse a servidores MCP remotos. Este es el transporte más ampliamente soportado para servicios basados en la nube.

# Sintaxis básica
claude mcp add --transport http <name> <url>

# Ejemplo real: Conectar a Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Ejemplo con token Bearer
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Opción 2: Agregar un servidor SSE remoto

# Sintaxis básica
claude mcp add --transport sse <name> <url>

# Ejemplo real: Conectar a Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Ejemplo con encabezado de autenticación
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Opción 3: Agregar un servidor stdio local

Los servidores stdio se ejecutan como procesos locales en su máquina. Son ideales para herramientas que necesitan acceso directo al sistema o scripts personalizados.

# Sintaxis básica
claude mcp add [options] <name> -- <command> [args...]

# Ejemplo real: Agregar servidor Airtable
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

Gestión de sus servidores

Una vez configurados, puede gestionar sus servidores MCP con estos comandos:

# Listar todos los servidores configurados
claude mcp list

# Obtener detalles para un servidor específico
claude mcp get github

# Eliminar un servidor
claude mcp remove github

# (dentro de Claude Code) Verificar estado del servidor
/mcp

El panel /mcp muestra el recuento de herramientas junto a cada servidor conectado e indica los servidores que anuncian la capacidad de herramientas pero no exponen ninguna herramienta.

El nombre del servidor workspace está reservado para uso interno. Si su configuración define un servidor con ese nombre, Claude Code lo omite al cargar y muestra una advertencia pidiéndole que lo renombre.

Actualizaciones dinámicas de herramientas

Claude Code admite notificaciones list_changed de MCP, permitiendo que los servidores MCP actualicen dinámicamente sus herramientas disponibles, indicaciones y recursos sin requerir que se desconecte y reconecte. Cuando un servidor MCP envía una notificación list_changed, Claude Code actualiza automáticamente las capacidades disponibles de ese servidor.

Reconexión automática

Si un servidor HTTP o SSE se desconecta durante la sesión, Claude Code se reconecta automáticamente con retroceso exponencial: hasta cinco intentos, comenzando con un retraso de un segundo y duplicándose cada vez. El servidor aparece como pendiente en /mcp mientras la reconexión está en progreso. Después de cinco intentos fallidos, el servidor se marca como fallido y puede reintentar manualmente desde /mcp. Los servidores stdio son procesos locales y no se reconectan automáticamente.

El mismo retroceso se aplica cuando un servidor HTTP o SSE falla su conexión inicial al iniciar. A partir de v2.1.121, Claude Code reintenta la conexión inicial hasta tres veces en errores transitorios como una respuesta 5xx, una conexión rechazada o un tiempo de espera agotado, luego marca el servidor como fallido si aún no puede conectarse. Los errores de autenticación y no encontrado no se reintentan porque requieren un cambio de configuración para resolverse.

Mensajes push con canales

Un servidor MCP también puede enviar mensajes directamente a su sesión para que Claude pueda reaccionar a eventos externos como resultados de CI, alertas de monitoreo o mensajes de chat. Para habilitar esto, su servidor declara la capacidad claude/channel y usted la activa con la bandera --channels al iniciar. Vea Canales para usar un canal oficialmente soportado, o Referencia de canales para construir el suyo propio.

Servidores MCP proporcionados por plugins

Los plugins pueden agrupar servidores MCP, proporcionando automáticamente herramientas e integraciones cuando el plugin está habilitado. Los servidores MCP de plugins funcionan de manera idéntica a los servidores configurados por el usuario.

Cómo funcionan los servidores MCP de plugins:

• Los plugins definen servidores MCP en .mcp.json en la raíz del plugin o en línea en plugin.json
• Cuando un plugin está habilitado, sus servidores MCP se inician automáticamente
• Las herramientas MCP del plugin aparecen junto a las herramientas MCP configuradas manualmente
• Los servidores de plugins se gestionan a través de la instalación de plugins (no mediante comandos /mcp)

Ejemplo de configuración MCP de plugin:

En .mcp.json en la raíz del plugin:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

O en línea en plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Características de MCP de plugins:

• Ciclo de vida automático: Al iniciar la sesión, los servidores de los plugins habilitados se conectan automáticamente. Si habilita o deshabilita un plugin durante una sesión, ejecute /reload-plugins para conectar o desconectar sus servidores MCP
• Variables de entorno: Use ${CLAUDE_PLUGIN_ROOT} para archivos agrupados en el plugin y ${CLAUDE_PLUGIN_DATA} para estado persistente que sobrevive a las actualizaciones de plugins
• Acceso a variables de entorno del usuario: Acceso a las mismas variables de entorno que los servidores configurados manualmente
• Múltiples tipos de transporte: Soporte para transportes stdio, SSE e HTTP (el soporte de transporte puede variar según el servidor)

Visualización de servidores MCP de plugins:

# Dentro de Claude Code, vea todos los servidores MCP incluyendo los de plugins
/mcp

Los servidores de plugins aparecen en la lista con indicadores que muestran que provienen de plugins.

Beneficios de los servidores MCP de plugins:

• Distribución agrupada: Herramientas y servidores empaquetados juntos
• Configuración automática: No se necesita configuración manual de MCP
• Consistencia del equipo: Todos obtienen las mismas herramientas cuando se instala el plugin

Vea la referencia de componentes de plugins para detalles sobre cómo agrupar servidores MCP con plugins.

Alcances de instalación de MCP

Los servidores MCP se pueden configurar en tres alcances. El alcance que elija controla en qué proyectos se carga el servidor y si la configuración se comparte con su equipo. Los administradores también pueden implementar servidores a nivel empresarial a través de configuración administrada.

Alcance local

El alcance local es el predeterminado. Un servidor con alcance local se carga solo en el proyecto donde lo agregó y permanece privado para usted. Claude Code lo almacena en ~/.claude.json bajo la ruta de ese proyecto, por lo que el mismo servidor no aparecerá en sus otros proyectos. Use el alcance local para servidores de desarrollo personal, configuraciones experimentales o servidores con credenciales que no desea en el control de versiones.

# Agregar un servidor con alcance local (predeterminado)
claude mcp add --transport http stripe https://mcp.stripe.com

# Especificar explícitamente alcance local
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

El comando escribe el servidor en la entrada de su proyecto actual dentro de ~/.claude.json. El ejemplo a continuación muestra el resultado cuando lo ejecuta desde /path/to/your/project:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Alcance de proyecto

Los servidores con alcance de proyecto habilitan la colaboración en equipo al almacenar configuraciones en un archivo .mcp.json en el directorio raíz de su proyecto. Este archivo está diseñado para ser verificado en el control de versiones, asegurando que todos los miembros del equipo tengan acceso a las mismas herramientas y servicios MCP. Cuando agrega un servidor con alcance de proyecto, Claude Code crea o actualiza automáticamente este archivo con la estructura de configuración apropiada.

# Agregar un servidor con alcance de proyecto
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

El archivo .mcp.json resultante sigue un formato estandarizado:

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

Por razones de seguridad, Claude Code solicita aprobación antes de usar servidores con alcance de proyecto desde archivos .mcp.json. Si necesita restablecer estas opciones de aprobación, use el comando claude mcp reset-project-choices.

Alcance de usuario

Los servidores con alcance de usuario se almacenan en ~/.claude.json y proporcionan accesibilidad entre proyectos, haciéndolos disponibles en todos los proyectos en su máquina mientras permanecen privados para su cuenta de usuario. Este alcance funciona bien para servidores de utilidad personal, herramientas de desarrollo o servicios que usa frecuentemente en diferentes proyectos.

# Agregar un servidor de usuario
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Jerarquía de alcance y precedencia

Cuando el mismo servidor está definido en más de un lugar, Claude Code se conecta a él una sola vez, usando la definición de la fuente de mayor precedencia:

1. Alcance local
2. Alcance de proyecto
3. Alcance de usuario
4. Servidores proporcionados por plugins
5. Conectores de claude.ai

Los tres alcances coinciden duplicados por nombre. Los plugins y conectores coinciden por punto final, por lo que uno que apunta a la misma URL o comando que un servidor anterior se trata como un duplicado.

Expansión de variables de entorno en .mcp.json

Claude Code admite la expansión de variables de entorno en archivos .mcp.json, permitiendo que los equipos compartan configuraciones mientras mantienen flexibilidad para rutas específicas de máquinas y valores sensibles como claves API.

Sintaxis soportada:

• ${VAR} - Se expande al valor de la variable de entorno VAR
• ${VAR:-default} - Se expande a VAR si está establecida, de lo contrario usa default

Ubicaciones de expansión: Las variables de entorno se pueden expandir en:

• command - La ruta del ejecutable del servidor
• args - Argumentos de línea de comandos
• env - Variables de entorno pasadas al servidor
• url - Para tipos de servidor HTTP
• headers - Para autenticación de servidor HTTP

Ejemplo con expansión de variables:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Si una variable de entorno requerida no está establecida y no tiene un valor predeterminado, Claude Code no podrá analizar la configuración.

Ejemplos prácticos

{/* ### Ejemplo: Automatizar pruebas de navegador con Playwright

claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest

Luego escriba y ejecute pruebas de navegador:

Test if the login flow works with test@example.com

Take a screenshot of the checkout page on mobile

Verify that the search feature returns results
``` */}

### Ejemplo: Monitorear errores con Sentry

```bash theme={null}
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Autentíquese con su cuenta de Sentry:

/mcp

Luego depure problemas de producción:

¿Cuáles son los errores más comunes en las últimas 24 horas?

Muéstrame el seguimiento de pila para el error ID abc123

¿Qué despliegue introdujo estos nuevos errores?

Ejemplo: Conectar a GitHub para revisiones de código

El servidor MCP remoto de GitHub se autentica con un token de acceso personal de GitHub pasado como encabezado. Para obtener uno, abra su configuración de token de GitHub, genere un nuevo token de grano fino con acceso a los repositorios con los que desea que Claude trabaje, luego agregue el servidor:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Luego trabaje con GitHub:

Revise el PR #456 y sugiera mejoras

Cree un nuevo problema para el error que acabamos de encontrar

Muéstrame todos los PR abiertos asignados a mí

Ejemplo: Consultar su base de datos PostgreSQL

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

Luego consulte su base de datos de forma natural:

¿Cuál es nuestro ingreso total este mes?

Muéstrame el esquema para la tabla de pedidos

Encuentre clientes que no han realizado una compra en 90 días

Autenticarse con servidores MCP remotos

Muchos servidores MCP basados en la nube requieren autenticación. Claude Code admite OAuth 2.0 para conexiones seguras.

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

/mcp

Usar un puerto de devolución de llamada OAuth fijo

Algunos servidores MCP requieren un URI de redireccionamiento específico registrado de antemano. De forma predeterminada, Claude Code elige un puerto disponible aleatorio para la devolución de llamada de OAuth. Use --callback-port para fijar el puerto de modo que coincida con un URI de redireccionamiento preregistrado de la forma http://localhost:PORT/callback.

Puede usar --callback-port por sí solo (con registro dinámico de clientes) o junto con --client-id (con credenciales preconfiguradas).

# Puerto de devolución de llamada fijo con registro dinámico de clientes
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Usar credenciales OAuth preconfiguradas

Algunos servidores MCP no admiten configuración automática de OAuth mediante Registro Dinámico de Clientes. Si ve un error como "Incompatible auth server: does not support dynamic client registration", el servidor requiere credenciales preconfiguradas. Claude Code también admite servidores que usan un Documento de Metadatos de ID de Cliente (CIMD) en lugar de Registro Dinámico de Clientes, y los descubre automáticamente. Si el descubrimiento automático falla, registre una aplicación OAuth a través del portal de desarrolladores del servidor primero, luego proporcione las credenciales al agregar el servidor.

claude mcp add --transport http \
--client-id your-client-id --client-secret --callback-port 8080 \
my-server https://mcp.example.com/mcp

claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
--client-secret

claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
--client-id your-client-id --client-secret --callback-port 8080 \
my-server https://mcp.example.com/mcp

Anular el descubrimiento de metadatos de OAuth

Apunte Claude Code a una URL de metadatos de servidor de autorización OAuth específica para omitir la cadena de descubrimiento predeterminada. De forma predeterminada, Claude Code primero verifica los Metadatos de Recursos Protegidos RFC 9728 en /.well-known/oauth-protected-resource, luego recurre a los metadatos del servidor de autorización RFC 8414 en /.well-known/oauth-authorization-server.

Establezca authServerMetadataUrl en el objeto oauth de la configuración de su servidor en .mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

La URL debe usar https://. authServerMetadataUrl requiere Claude Code v2.1.64 o posterior. Los scopes_supported de la URL de metadatos anulan los alcances que el servidor ascendente anuncia.

Restringir alcances de OAuth

Establezca oauth.scopes para fijar los alcances que Claude Code solicita durante el flujo de autorización. Esta es la forma soportada de restringir un servidor MCP a un subconjunto aprobado por el equipo de seguridad cuando el servidor de autorización ascendente anuncia más alcances de los que desea otorgar. El valor es una cadena única separada por espacios, que coincide con el formato del parámetro scope en RFC 6749 §3.3.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes tiene precedencia sobre tanto authServerMetadataUrl como los alcances que el servidor descubre en /.well-known. Déjelo sin establecer para permitir que el servidor MCP determine el conjunto de alcances solicitados.

Si el servidor de autorización anuncia offline_access en scopes_supported, Claude Code lo añade a los alcances fijados para que el token de acceso pueda actualizarse sin un nuevo inicio de sesión en el navegador.

Si el servidor luego devuelve un 403 insufficient_scope para una llamada de herramienta, Claude Code se reautentica con los mismos alcances fijados. Amplíe oauth.scopes cuando una herramienta que necesita requiera un alcance fuera del fijo.

Usar encabezados dinámicos para autenticación personalizada

Si su servidor MCP usa un esquema de autenticación diferente a OAuth (como Kerberos, tokens de corta duración o un SSO interno), use headersHelper para generar encabezados de solicitud en el momento de la conexión. Claude Code ejecuta el comando y fusiona su salida en los encabezados de conexión.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

El comando también puede ser en línea:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

Requisitos:

• El comando debe escribir un objeto JSON de pares clave-valor de cadena en stdout
• El comando se ejecuta en un shell con un tiempo de espera de 10 segundos
• Los encabezados dinámicos anulan cualquier headers estático con el mismo nombre

El ayudante se ejecuta nuevamente en cada conexión (al iniciar la sesión y al reconectar). No hay almacenamiento en caché, por lo que su script es responsable de cualquier reutilización de tokens.

Claude Code establece estas variables de entorno al ejecutar el ayudante:

Use estas para escribir un único script de ayudante que sirva múltiples servidores MCP.

Agregar servidores MCP desde configuración JSON

Si tiene una configuración JSON para un servidor MCP, puede agregarla directamente:

# Sintaxis básica
claude mcp add-json <name> '<json>'

# Ejemplo: Agregar un servidor HTTP con configuración JSON
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Ejemplo: Agregar un servidor stdio con configuración JSON
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Ejemplo: Agregar un servidor HTTP con credenciales OAuth preconfiguradas
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

claude mcp get weather-api

Importar servidores MCP desde Claude Desktop

Si ya ha configurado servidores MCP en Claude Desktop, puede importarlos:

# Sintaxis básica 
claude mcp add-from-claude-desktop 

claude mcp list 

Usar servidores MCP desde Claude.ai

Si ha iniciado sesión en Claude Code con una cuenta de Claude.ai, los servidores MCP que ha agregado en Claude.ai están automáticamente disponibles en Claude Code:

/mcp

Un servidor que ha agregado en Claude Code tiene precedencia sobre un conector de claude.ai que apunta a la misma URL. Cuando esto sucede, /mcp enumera el conector como oculto y muestra cómo eliminar el duplicado si prefiere usar el conector.

Para desactivar servidores MCP de Claude.ai en Claude Code, establezca la variable de entorno ENABLE_CLAUDEAI_MCP_SERVERS en false:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Usar Claude Code como servidor MCP

Puede usar Claude Code mismo como servidor MCP al que otras aplicaciones pueden conectarse:

# Iniciar Claude como servidor MCP stdio
claude mcp serve

Puede usar esto en Claude Desktop agregando esta configuración a claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Límites de salida de MCP y advertencias

Cuando las herramientas MCP producen salidas grandes, Claude Code ayuda a gestionar el uso de tokens para evitar abrumar el contexto de su conversación:

• Umbral de advertencia de salida: Claude Code muestra una advertencia cuando la salida de cualquier herramienta MCP excede 10,000 tokens
• Límite configurable: Puede ajustar los tokens de salida MCP máximos permitidos usando la variable de entorno MAX_MCP_OUTPUT_TOKENS
• Límite predeterminado: El máximo predeterminado es 25,000 tokens
• Alcance: La variable de entorno se aplica a herramientas que no declaran su propio límite. Las herramientas que establecen anthropic/maxResultSizeChars usan ese valor en su lugar para contenido de texto, independientemente de lo que MAX_MCP_OUTPUT_TOKENS esté establecido. Las herramientas que devuelven datos de imagen aún están sujetas a MAX_MCP_OUTPUT_TOKENS

Para aumentar el límite para herramientas que producen salidas grandes:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Esto es particularmente útil cuando se trabaja con servidores MCP que:

• Consultan grandes conjuntos de datos o bases de datos
• Generan reportes o documentación detallados
• Procesan archivos de registro extensos o información de depuración

Aumentar el límite para una herramienta específica

Si está construyendo un servidor MCP, puede permitir que herramientas individuales devuelvan resultados más grandes que el umbral predeterminado de persistencia en disco estableciendo _meta["anthropic/maxResultSizeChars"] en la entrada de la herramienta en la respuesta tools/list. Claude Code aumenta el umbral de esa herramienta al valor anotado, hasta un límite máximo de 500,000 caracteres.

Esto es útil para herramientas que devuelven salidas inherentemente grandes pero necesarias, como esquemas de bases de datos o árboles de archivos completos. Sin la anotación, los resultados que exceden el umbral predeterminado se persisten en disco y se reemplazan con una referencia de archivo en la conversación.

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

La anotación se aplica independientemente de MAX_MCP_OUTPUT_TOKENS para contenido de texto, por lo que los usuarios no necesitan aumentar la variable de entorno para herramientas que la declaran. Las herramientas que devuelven datos de imagen aún están sujetas al límite de tokens.

Responder a solicitudes de elicitación de MCP

Los servidores MCP pueden solicitar entrada estructurada de usted durante una tarea usando elicitación. Cuando un servidor necesita información que no puede obtener por sí solo, Claude Code muestra un diálogo interactivo y pasa su respuesta de vuelta al servidor. No se requiere configuración de su parte: los diálogos de elicitación aparecen automáticamente cuando un servidor los solicita.

Los servidores pueden solicitar entrada de dos formas:

• Modo de formulario: Claude Code muestra un diálogo con campos de formulario definidos por el servidor (por ejemplo, un indicador de nombre de usuario y contraseña). Complete los campos y envíe.
• Modo de URL: Claude Code abre una URL del navegador para autenticación o aprobación. Complete el flujo en el navegador, luego confirme en la CLI.

Para responder automáticamente a solicitudes de elicitación sin mostrar un diálogo, use el hook Elicitation.

Si está construyendo un servidor MCP que usa elicitación, vea la especificación de elicitación de MCP para detalles de protocolo y ejemplos de esquema.

Usar recursos MCP

Los servidores MCP pueden exponer recursos que puede referenciar usando menciones @, similar a cómo referencia archivos.

Referenciar recursos MCP

¿Puede analizar @github:issue://123 y sugerir una solución?

Por favor revise la documentación de API en @docs:file://api/authentication

Compare @postgres:schema://users con @docs:file://database/user-model

Escalar con MCP Tool Search

Tool Search mantiene el uso de contexto MCP bajo al diferir las definiciones de herramientas hasta que Claude las necesite. Solo los nombres de herramientas se cargan al iniciar la sesión, por lo que agregar más servidores MCP tiene un impacto mínimo en su ventana de contexto.

Cómo funciona

Tool Search está habilitado de forma predeterminada. Las herramientas MCP se difieren en lugar de cargarse en el contexto de antemano, y Claude usa una herramienta de búsqueda para descubrir las relevantes cuando una tarea las necesita. Solo las herramientas que Claude realmente usa entran en el contexto. Desde su perspectiva, las herramientas MCP funcionan exactamente como antes.

Si prefiere carga basada en umbral, establezca ENABLE_TOOL_SEARCH=auto para cargar esquemas de antemano cuando se ajusten dentro del 10% de la ventana de contexto y diferir solo el desbordamiento. Vea Configurar búsqueda de herramientas para todas las opciones.

Para autores de servidores MCP

Si está construyendo un servidor MCP, el campo de instrucciones del servidor se vuelve más útil con Tool Search habilitado. Las instrucciones del servidor ayudan a Claude a entender cuándo buscar sus herramientas, similar a cómo funcionan las skills.

Agregue instrucciones claras y descriptivas del servidor que expliquen:

• Qué categoría de tareas manejan sus herramientas
• Cuándo Claude debe buscar sus herramientas
• Capacidades clave que proporciona su servidor

Claude Code trunca descripciones de herramientas e instrucciones del servidor en 2KB cada una. Manténgalas concisas para evitar truncamiento, y ponga detalles críticos cerca del inicio.

Configurar búsqueda de herramientas

Tool Search está habilitado de forma predeterminada: las herramientas MCP se difieren y se descubren bajo demanda. Está deshabilitado de forma predeterminada en Vertex AI, que no acepta el encabezado beta de búsqueda de herramientas, y cuando ANTHROPIC_BASE_URL apunta a un host que no es de primera parte, ya que la mayoría de los proxies no reenvían bloques tool_reference. Establezca ENABLE_TOOL_SEARCH explícitamente para optar por participar. Esta característica requiere modelos que admitan bloques tool_reference: Sonnet 4 y posterior, u Opus 4 y posterior. Los modelos Haiku no admiten búsqueda de herramientas.

Controle el comportamiento de búsqueda de herramientas con la variable de entorno ENABLE_TOOL_SEARCH:

# Usar un umbral personalizado del 5%
ENABLE_TOOL_SEARCH=auto:5 claude

# Desactivar búsqueda de herramientas completamente
ENABLE_TOOL_SEARCH=false claude

O establezca el valor en su campo env de settings.json.

También puede desactivar la herramienta ToolSearch específicamente:

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

Eximir un servidor del diferimiento

Si las herramientas de un servidor deben ser siempre visibles para Claude sin un paso de búsqueda, establezca alwaysLoad en true en la configuración de ese servidor. Cada herramienta de ese servidor se carga entonces en el contexto al iniciar la sesión independientemente de la configuración ENABLE_TOOL_SEARCH. Use esto para un pequeño número de herramientas que Claude necesita en cada turno, ya que cada herramienta de antemano consume contexto que de otro modo estaría disponible para su conversación.

La siguiente entrada .mcp.json exime un servidor HTTP mientras deja otros servidores diferidos:

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

El campo alwaysLoad está disponible en todos los tipos de servidor y requiere Claude Code v2.1.121 o posterior. Un servidor MCP también puede marcar herramientas individuales como siempre cargadas incluyendo "anthropic/alwaysLoad": true en el objeto _meta de la herramienta, que tiene el mismo efecto solo para esa herramienta.

Establecer alwaysLoad: true también bloquea el inicio hasta que el servidor se conecte, limitado al tiempo de espera de conexión estándar de 5 segundos. Esto se aplica incluso cuando MCP_CONNECTION_NONBLOCKING=1 está establecido, ya que las herramientas deben estar presentes cuando se construye el primer mensaje. Otros servidores aún se conectan en segundo plano cuando el modo no bloqueante está habilitado.

Usar indicaciones MCP como comandos

Los servidores MCP pueden exponer indicaciones que se vuelven disponibles como comandos en Claude Code.

Ejecutar indicaciones MCP

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug en flujo de inicio de sesión" high

Configuración MCP gestionada

Para organizaciones que necesitan control centralizado sobre servidores MCP, Claude Code admite dos opciones de configuración:

1. Control exclusivo con managed-mcp.json: Implemente un conjunto fijo de servidores MCP que los usuarios no pueden modificar ni extender
2. Control basado en políticas con listas de permitidos/bloqueados: Permita que los usuarios agreguen sus propios servidores, pero restrinja cuáles están permitidos

Estas opciones permiten a los administradores de TI:

• Controlar a qué servidores MCP pueden acceder los empleados: Implemente un conjunto estandarizado de servidores MCP aprobados en toda la organización
• Prevenir servidores MCP no autorizados: Restrinja a los usuarios de agregar servidores MCP no aprobados
• Desactivar MCP completamente: Elimine completamente la funcionalidad MCP si es necesario

Opción 1: Control exclusivo con managed-mcp.json

Cuando implementa un archivo managed-mcp.json, toma control exclusivo sobre todos los servidores MCP. Los usuarios no pueden agregar, modificar ni usar ningún servidor MCP que no esté definido en este archivo. Este es el enfoque más simple para organizaciones que desean control completo.

Los administradores del sistema implementan el archivo de configuración en un directorio de todo el sistema:

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux y WSL: /etc/claude-code/managed-mcp.json
• Windows: C:\Program Files\ClaudeCode\managed-mcp.json

El archivo managed-mcp.json usa el mismo formato que un archivo .mcp.json estándar:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

Opción 2: Control basado en políticas con listas de permitidos y bloqueados

En lugar de tomar control exclusivo, los administradores pueden permitir que los usuarios configuren sus propios servidores MCP mientras aplican restricciones sobre qué servidores están permitidos. Este enfoque usa allowedMcpServers y deniedMcpServers en el archivo de configuración gestionada.

Opciones de restricción

Cada entrada en la lista de permitidos o bloqueados puede restringir servidores de tres formas:

1. Por nombre de servidor (serverName): Coincide con el nombre configurado del servidor
2. Por comando (serverCommand): Coincide con el comando exacto y los argumentos utilizados para iniciar servidores stdio
3. Por patrón de URL (serverUrl): Coincide con URLs de servidor remoto con soporte de comodín

Importante: Cada entrada debe tener exactamente uno de serverName, serverCommand o serverUrl.

Configuración de ejemplo

{
  "allowedMcpServers": [
    // Permitir por nombre de servidor
    { "serverName": "github" },
    { "serverName": "sentry" },

    // Permitir por comando exacto (para servidores stdio)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // Permitir por patrón de URL (para servidores remotos)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // Bloquear por nombre de servidor
    { "serverName": "dangerous-server" },

    // Bloquear por comando exacto (para servidores stdio)
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // Bloquear por patrón de URL (para servidores remotos)
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

Cómo funcionan las restricciones basadas en comandos

Coincidencia exacta:

• Los arrays de comandos deben coincidir exactamente - tanto el comando como todos los argumentos en el orden correcto
• Ejemplo: ["npx", "-y", "server"] NO coincidirá con ["npx", "server"] o ["npx", "-y", "server", "--flag"]

Comportamiento del servidor stdio:

• Cuando la lista de permitidos contiene cualquier entrada serverCommand, los servidores stdio deben coincidir con uno de esos comandos
• Los servidores stdio no pueden pasar solo por nombre cuando hay restricciones de comando presentes
• Esto asegura que los administradores puedan aplicar qué comandos están permitidos ejecutarse

Comportamiento del servidor no-stdio:

• Los servidores remotos (HTTP, SSE, WebSocket) usan coincidencia basada en URL cuando existen entradas serverUrl en la lista de permitidos
• Si no existen entradas de URL, los servidores remotos recurren a coincidencia basada en nombre
• Las restricciones de comando no se aplican a servidores remotos

Cómo funcionan las restricciones basadas en URL

Los patrones de URL admiten comodines usando * para coincidir con cualquier secuencia de caracteres. Esto es útil para permitir dominios completos o subdominios.

Ejemplos de comodín:

• https://mcp.company.com/* - Permitir todas las rutas en un dominio específico
• https://*.example.com/* - Permitir cualquier subdominio de example.com
• http://localhost:*/* - Permitir cualquier puerto en localhost

La coincidencia de nombres de host no distingue entre mayúsculas y minúsculas e ignora un punto FQDN final, coincidiendo con la semántica de DNS. Un patrón como *://Mcp.Example.com/* coincide con https://mcp.example.com/api, y https://mcp.example.com. se trata igual que https://mcp.example.com. Los esquemas y rutas permanecen sensibles a mayúsculas y minúsculas.

Comportamiento del servidor remoto:

• Cuando la lista de permitidos contiene cualquier entrada serverUrl, los servidores remotos deben coincidir con uno de esos patrones de URL
• Los servidores remotos no pueden pasar solo por nombre cuando hay restricciones de URL presentes
• Esto asegura que los administradores puedan aplicar qué puntos finales remotos están permitidos

{
"allowedMcpServers": [
{ "serverUrl": "https://mcp.company.com/*" },
{ "serverUrl": "https://*.internal.corp/*" }
]
}

{
"allowedMcpServers": [
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverCommand": ["npx", "-y", "approved-package"] }
]
}

{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverName": "internal-tool" }
]
}

Comportamiento de la lista de permitidos (allowedMcpServers)

• undefined (predeterminado): Sin restricciones - los usuarios pueden configurar cualquier servidor MCP
• Array vacío []: Bloqueo completo - los usuarios no pueden configurar ningún servidor MCP
• Lista de entradas: Los usuarios solo pueden configurar servidores que coincidan por nombre, comando o patrón de URL

Comportamiento de la lista de bloqueados (deniedMcpServers)

• undefined (predeterminado): Ningún servidor está bloqueado
• Array vacío []: Ningún servidor está bloqueado
• Lista de entradas: Los servidores especificados están explícitamente bloqueados en todos los alcances

Notas importantes

• La Opción 1 y la Opción 2 se pueden combinar: Si existe managed-mcp.json, tiene control exclusivo y los usuarios no pueden agregar servidores. Las listas de permitidos/bloqueados aún se aplican a los servidores gestionados mismos.
• La lista de bloqueados tiene precedencia absoluta: Si un servidor coincide con una entrada de lista de bloqueados (por nombre, comando o URL), será bloqueado incluso si está en la lista de permitidos
• Las restricciones basadas en nombre, comando y URL funcionan juntas: un servidor pasa si coincide con cualquiera de una entrada de nombre, una entrada de comando o un patrón de URL (a menos que esté bloqueado por lista de bloqueados)