Conectar Claude Code a herramientas mediante MCP

Aprenda cómo conectar Claude Code a sus herramientas con el Model Context Protocol.

Claude Code puede conectarse a cientos de herramientas externas y fuentes de datos a través del Model Context Protocol (MCP), un estándar de código abierto para integraciones de IA con herramientas. Los servidores MCP dan a Claude Code acceso a sus herramientas, bases de datos y APIs.

Conecte un servidor cuando se encuentre copiando datos en el chat desde otra herramienta, como un rastreador de problemas o un panel de monitoreo. Una vez conectado, Claude puede leer y actuar en ese sistema directamente en lugar de trabajar con lo que pegue.

Si está conectando su primer servidor, comience con el inicio rápido de MCP para un recorrido paso a paso. Esta página es la referencia completa.

Qué puede hacer con MCP

Con servidores MCP conectados, puede pedirle a Claude Code que:

• Implemente características desde rastreadores de problemas: "Agregue la característica descrita en el problema JIRA ENG-4521 y cree un PR en GitHub."
• Analice datos de monitoreo: "Verifique Sentry y Statsig para verificar el uso de la característica descrita en ENG-4521."
• Consulte bases de datos: "Encuentre correos electrónicos de 10 usuarios aleatorios que utilizaron la característica ENG-4521, basándose en nuestra base de datos PostgreSQL."
• Integre diseños: "Actualice nuestra plantilla de correo electrónico estándar basándose en los nuevos diseños de Figma que se publicaron en Slack"
• Automatice flujos de trabajo: "Cree borradores de Gmail invitando a estos 10 usuarios a una sesión de retroalimentación sobre la nueva característica."
• Reaccione a eventos externos: Un servidor MCP también puede actuar como un canal que envía mensajes a su sesión, para que Claude reaccione a mensajes de Telegram, chats de Discord o eventos de webhook mientras está fuera.

Buscar y crear servidores MCP

Explore conectores revisados en el Directorio de Anthropic. Los conectores del Directorio utilizan la misma infraestructura MCP que Claude Code, por lo que puede agregar cualquier servidor remoto listado allí con claude mcp add.

Para crear su propio servidor, consulte la guía del servidor MCP para los fundamentos del protocolo y la documentación de construcción de conectores de Claude para autenticación, pruebas y envío al Directorio.

También puede hacer que Claude cree un servidor para usted con el plugin oficial mcp-server-dev.

/plugin install mcp-server-dev@claude-plugins-official

/mcp-server-dev:build-mcp-server

Instalación de servidores MCP

Los servidores MCP se pueden configurar de varias formas 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"

Cuando configure servidores MCP a través de JSON en .mcp.json, ~/.claude.json, o claude mcp add-json, el campo type acepta streamable-http como un alias para http. La especificación de MCP utiliza el nombre streamable-http para este transporte, por lo que las configuraciones copiadas de la documentación del servidor funcionan sin modificación.

Una entrada JSON que tiene una url pero no tiene type es un error de configuración, porque Claude Code lee una entrada sin type como un servidor stdio. Claude Code omite ese servidor e informa MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. Antes de v2.1.202, Claude Code informaba esta configuración incorrecta como command: expected string, received undefined.

En ejecuciones con --output-format stream-json, Claude Code también informa una entrada --mcp-config omitida en el evento system/init del campo mcp_server_errors, por lo que los scripts pueden detectar que el servidor nunca se cargó. Esto requiere Claude Code v2.1.219 o posterior.

Opción 2: Agregar un servidor SSE remoto

Algunos servicios aún exponen solo un punto final SSE. Agréguelos con el mismo comando claude mcp add --transport http <name> <url> que un servidor HTTP. Claude Code intenta el transporte HTTP primero y cambia a SSE cuando el servidor no lo acepta. El cambio automático requiere Claude Code v2.1.265 o posterior.

En una versión anterior, o para conectarse sobre SSE directamente, pase --transport sse en su lugar:

# 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.

Claude Code establece CLAUDE_PROJECT_DIR en el entorno del servidor generado a la raíz del proyecto, por lo que su servidor puede resolver rutas relativas al proyecto sin depender del directorio de trabajo. Este es el mismo directorio que los hooks reciben en su variable CLAUDE_PROJECT_DIR. Léalo desde dentro de su proceso de servidor, por ejemplo process.env.CLAUDE_PROJECT_DIR en Node o os.environ["CLAUDE_PROJECT_DIR"] en Python.

CLAUDE_PROJECT_DIR es la raíz del proyecto estable y no cambia cuando agrega o elimina directorios de trabajo durante la sesión. Un servidor que limita su propio acceso al sistema de archivos a un conjunto de directorios permitidos debe implementar la solicitud MCP roots/list en su lugar. Claude Code responde a roots/list con el directorio de lanzamiento de la sesión más cada directorio de trabajo adicional que ha otorgado con --add-dir, /add-dir, o la configuración additionalDirectories. Claude Code envía notifications/roots/list_changed cuando ese conjunto cambia. Antes de v2.1.203, roots/list devolvía solo el directorio de lanzamiento y Claude Code no enviaba notifications/roots/list_changed.

Esta variable se establece en el entorno del servidor, no en el entorno propio de Claude Code, por lo que hacer referencia a ella mediante la expansión ${VAR} en un archivo .mcp.json con alcance de proyecto o usuario en command o args requiere un valor predeterminado como ${CLAUDE_PROJECT_DIR:-.}. Las configuraciones MCP proporcionadas por plugins sustituyen ${CLAUDE_PROJECT_DIR} directamente y no necesitan el valor predeterminado.

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

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

Opción 4: Agregar un servidor WebSocket remoto

Los servidores WebSocket mantienen una conexión bidireccional persistente, que es adecuada para servidores MCP remotos que envían eventos a Claude sin ser solicitados. Use HTTP en su lugar cuando su servidor solo responda a solicitudes, ya que HTTP admite OAuth y la bandera claude mcp add --transport, mientras que WebSocket no admite ninguno de los dos.

Configure servidores WebSocket en .mcp.json o con claude mcp add-json:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

La entrada type: "ws" acepta los mismos campos url, headers, headersHelper, timeout y alwaysLoad que http. La autenticación es solo por encabezado, por lo que pase un token estático en headers o genere uno en el momento de la conexión con headersHelper. La bandera claude mcp add --transport no acepta ws.

Agregar un servidor desde instrucciones de configuración escritas para otro cliente

Los servidores MCP no son específicos de Claude Code, por lo que las instrucciones de configuración de un servidor pueden estar escritas para Claude Desktop, Cursor u otro cliente MCP y no dar ningún comando claude mcp add. Para agregar el servidor de todas formas, busque en esas instrucciones una de estas tres cosas:

• Una URL como https://mcp.example.com/mcp: el servidor es remoto.
• Un comando de lanzamiento como npx -y @example/mcp-server: el servidor se ejecuta en su máquina.
• Un bloque JSON mcpServers: configuración escrita para el archivo de configuración de otro cliente.

Cada uno es una de las entradas que las cuatro opciones en Instalación de servidores MCP toman. Encuentre la forma que tiene a continuación para convertirla en el comando que Claude Code acepta. Cada comando escribe en alcance local a menos que agregue --scope project o --scope user.

Desde una URL

Una URL significa que el servidor es remoto. Para un punto final https://, agréguelo con --transport http, o siga Opción 2 cuando las instrucciones digan que el punto final usa SSE. Para un punto final wss://, use Opción 4 en su lugar, ya que --transport no acepta ws:

claude mcp add --transport http example https://mcp.example.com/mcp

Si las instrucciones también dan una clave API o encabezado de token, páselo con --header como se muestra en Opción 1.

Desde un comando `npx`, `uvx` o binario

Un comando de lanzamiento significa que el servidor se ejecuta como un proceso stdio local. Ponga todo el comando después de --, para que Claude Code pase banderas como -y al comando que inicia el servidor en lugar de leerlas como sus propias opciones. Pase cualquier variable de entorno que las instrucciones pidan con --env, después del nombre del servidor y antes de --:

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

Opción 3 cubre el separador -- en su totalidad.

Desde un bloque JSON `mcpServers`

Un bloque mcpServers escrito para otro cliente MCP, como Claude Desktop, usa la clave contenedora y la forma de entrada que Claude Code lee. Pase a claude mcp add-json el objeto dentro de mcpServers, no el contenedor. Dos entradas necesitan una reparación primero:

• Una url sin type: agregue "type": "http", "type": "sse", o "type": "ws" para coincidir con el punto final. Claude Code lee una entrada sin type como un servidor stdio, por lo que una entrada url sin type falla.
• Una clave con caracteres distintos de letras, números, guiones e guiones bajos: elija un nombre de servidor que use solo esos caracteres. De lo contrario, la clave es el nombre del servidor.

Por ejemplo, este bloque:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

se convierte en este comando:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Agregar servidores MCP desde configuración JSON cubre el escape de shell y la bandera --scope para add-json. Para compartir el servidor con su equipo en su lugar, agregue --scope project, o agregue la entrada bajo mcpServers en .mcp.json en la raíz de su proyecto y confirme. Alcance de proyecto cubre cómo Claude Code carga y aprueba ese archivo.

Cada comando claude mcp add y claude mcp add-json imprime una línea Added .... Para verificar que Claude Code se conectó, ejecute claude mcp get <name>; Estado del servidor cubre los estados que muestra y el paso de aprobación para servidores .mcp.json.

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 notion

# Eliminar un servidor
claude mcp remove notion

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

Cuando elimina un servidor remoto, Claude Code también elimina los tokens OAuth y el registro de cliente que almacenó para ese servidor.

Estado del servidor

claude mcp add confirma una adición exitosa imprimiendo una línea Added ..., lo que significa que la configuración fue escrita. claude mcp list luego muestra un estado de salud junto a cada servidor que lista, como ✔ Connected, ! Needs authentication, o ✘ Failed to connect. Un estado de fallo significa que Claude Code no pudo conectarse a ese servidor, no que el comando list haya fallado.

Los estados en esta lista informan una decisión de configuración en lugar de un intento de conexión, por lo que Claude Code los imprime sin conectarse al servidor:

• ⏸ Pending approval (run `claude` to approve): un servidor con alcance de proyecto desde .mcp.json que aún no ha aprobado. Claude Code lo muestra tanto en claude mcp list como en claude mcp get <name>. Ejecute claude de forma interactiva para revisar y aprobar.
• ✘ Rejected (see disabledMcpjsonServers in settings): un servidor .mcp.json que una entrada disabledMcpjsonServers rechaza. Claude Code lo muestra solo en claude mcp get <name>.
• ⊘ Disabled for this project (re-enable via /mcp): un servidor que la lista disabledMcpServers del proyecto nombra. Claude Code lo muestra tanto en claude mcp list como en claude mcp get <name>. Active el servidor nuevamente desde el panel /mcp. Antes de v2.1.238, ambos comandos se conectaban a un servidor deshabilitado para verificar su salud e informaban el resultado de la conexión.

Los servidores WebSocket no aparecen en la salida de claude mcp list. Use claude mcp get <name> o el panel /mcp para verificarlos.

Aprobaciones de servidores de proyecto y confianza del espacio de trabajo

A partir de v2.1.196, claude mcp list y claude mcp get leen aprobaciones de .mcp.json solo desde archivos de configuración que no están comprometidos en el repositorio hasta que confíe en el espacio de trabajo ejecutando claude en él y aceptando el diálogo de confianza del espacio de trabajo. Un repositorio clonado no puede aprobar sus propios servidores: enableAllProjectMcpServers o enabledMcpjsonServers comprometido en el archivo .claude/settings.json del proyecto se ignora en una carpeta no confiable, y el servidor permanece en ⏸ Pending approval en lugar de estar conectado y verificado de salud.

Las aprobaciones de estas fuentes aún se aplican en una carpeta no confiable:

• su archivo ~/.claude/settings.json del usuario
• configuración gestionada
• configuración pasada con --settings

Claude Code también aplica aprobaciones desde un archivo .claude/settings.local.json sin rastrear, pero ejecuta git para verificar si el archivo está rastreado, y ejecuta esa verificación solo en una carpeta confiable. En una carpeta que nunca ha confiado, Claude Code espera el diálogo de confianza antes de aplicar las aprobaciones del archivo, a menos que la carpeta sea su directorio de configuración personal: su directorio de inicio, o un directorio cuyo .claude ha establecido como CLAUDE_CONFIG_DIR. Antes de v2.1.207, Claude Code aplicaba aprobaciones desde un archivo .claude/settings.local.json sin rastrear incluso en una carpeta que nunca había confiado.

Una entrada disabledMcpjsonServers en cualquier archivo de configuración aún rechaza el servidor.

Detalle del estado del servidor

En /mcp, incluyendo el menú de un servidor allí, y en el gestor /plugin, un servidor HTTP o SSE remoto que ha usado antes puede mostrar un estado cached como cached 2h ago · connects on first use · 5 tools. Claude Code cargó la lista de herramientas del servidor desde su caché de descubrimiento, guardado en una sesión anterior, en lugar de conectarse al inicio, y Claude Code conecta el servidor la primera vez que Claude llama a una de las herramientas del servidor. Las herramientas están disponibles desde su primer mensaje, por lo que no necesita hacer nada. El caché de descubrimiento y su estado cached requieren Claude Code v2.1.221 o posterior.

El caché de descubrimiento está desactivado de forma predeterminada a menos que un lanzamiento gradual lo haya habilitado para su cuenta. Establezca MCP_DISCOVERY_CACHE=1 para activarlo, o 0 para mantenerlo desactivado incluso cuando el lanzamiento lo haya habilitado. Antes de v2.1.238, el caché estaba activado de forma predeterminada.

Dos acciones en el menú de un servidor en /mcp también afectan la entrada de caché de ese servidor:

• Reconnect: en un servidor cached, Claude Code lo conecta ahora en lugar de en su primera llamada de herramienta y mantiene la entrada. En un servidor conectado o fallido, Claude Code lo reconecta y también descarta la entrada.
• Clear authentication: Claude Code revoca la autenticación del servidor y también descarta la entrada.

Después de descartar la entrada, Claude Code obtiene la lista de herramientas del servidor desde el servidor en lugar de desde el caché.

Cuando el estado de un servidor es ✘ Failed to connect, claude mcp list añade el detalle de fallo a esa línea de estado, y claude mcp get <name> lo muestra en una línea Issue:: el estado HTTP o código de error, más cualquier texto de error que el servidor devolvió. La vista de detalle del servidor en /mcp incluye el mismo texto reportado por el servidor en su fila Issue:. Claude Code redacta texto similar a credenciales de este detalle y nunca incluye la URL del servidor expandida, que puede llevar secretos. Claude Code no añade detalle a un estado ✘ Connection error, porque el texto de excepción que imprimiría allí puede incrustar esa URL. Antes de v2.1.219, ambos comandos mostraban solo el estado de fallo desnudo, sin el código de estado o el texto de error del servidor.

Cuando completa la autenticación desde /mcp y la conexión aún falla con un estado HTTP o un código de error de transporte, Claude Code añade ese código y el origen de la URL que intentó al mensaje que imprime después del intento. El origen es el esquema y host, más el puerto cuando la URL nombra uno, como https://mcp.example.com.

• La ruta y consulta nunca aparecen en ese mensaje.
• Para un servidor en el alcance local, proyecto, usuario o scope o en configuración MCP gestionada, el origen muestra el host tal como está escrito en esa configuración, por lo que una referencia ${VAR} en el host no se expande en el mensaje.
• Para un fallo sin estado o código de error, Claude Code muestra el texto de error sin el origen.

Un servidor remoto cuya configuración tiene una url vacía se muestra como not configured en /mcp, en claude mcp list, y en el gestor /plugin, y Claude Code no intenta conectarse a él. Un plugin puede incluir una entrada de marcador de posición como esta para un conector que configura más tarde, por lo que Claude Code no lo informa como un error o un problema de configuración. La vista de detalles del servidor en /mcp lee No URL configured for this server; establezca la url de la entrada para conectarse. Antes de v2.1.208, Claude Code informaba una url vacía como un problema de configuración con un aviso para reconectar.

Advertencias de configuración

Claude Code advierte sobre los problemas de configuración a continuación. Cada entrada dice qué verifica Claude Code y cómo borrar la advertencia:

• Espacios en blanco ocultos: Claude Code advierte cuando un valor de configuración MCP lleva espacios en blanco ocultos al principio o al final, que a menudo provienen de pegar un token con una nueva línea al final. Claude Code verifica command, url, cada entrada args, y los valores y nombres de clave bajo env y headers. Claude Code muestra la advertencia en la salida de claude mcp list y en /mcp, nombrando los campos afectados sin ecoar sus valores, por ejemplo Leading or trailing whitespace in: headers.Authorization. Claude Code no recorta el espacio en blanco y usa los valores exactamente como están escritos, por lo que edite la configuración para eliminarlo.
• Mismo nombre en más de un alcance: si define el mismo nombre de servidor en más de un alcance con diferentes puntos finales, Claude Code advierte sobre el conflicto en la salida de claude mcp list y en /mcp. Claude Code almacena inicios de sesión OAuth por punto final, por lo que cuando autentica la definición que se carga en un proyecto, aún necesita iniciar sesión por separado en un proyecto donde se carga una definición diferente. Mantenga el punto final que desea y elimine los otros con claude mcp remove <name> --scope <scope>. En la advertencia, Claude Code cita el punto final de cada alcance como está escrito en su configuración, con referencias ${VAR} sin expandir, por lo que nunca muestra un valor resuelto como una clave API.
• Nombres reservados: Claude Code reserva los nombres de sus servidores integrados, incluyendo workspace, claude-in-chrome, computer-use, Claude Preview, y Claude Browser. Si su configuración define un servidor con un nombre reservado, Claude Code lo omite al cargar y muestra una advertencia pidiéndole que lo renombre. claude mcp add rechaza un nombre reservado con un error. Claude Preview y Claude Browser ambos nombran el servidor integrado que el panel de vista previa de la aplicación de escritorio de Claude Code utiliza. Antes de v2.1.205, Claude Browser no estaba reservado, por lo que un servidor configurado por el usuario podría registrarse bajo ese nombre.
• Variable de entorno faltante: si una referencia ${VAR} en la configuración de un servidor nombra una variable que no está establecida y no tiene :-default, Claude Code advierte en la salida de claude mcp list y en /mcp, nombrando la variable, y aún carga el servidor con el texto ${VAR} sin expandir. Establezca la variable o agregue un fallback ${VAR:-default}.

Disponibilidad de herramientas

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.

Si su solicitud necesita herramientas de un servidor que aún se está conectando en segundo plano, Claude espera a que ese servidor continúe. Cómo sucede la espera depende de su configuración:

• Con búsqueda de herramientas, la predeterminada: la espera ocurre dentro de la llamada ToolSearch.
• Sin búsqueda de herramientas: Claude usa la herramienta WaitForMcpServers en su lugar. Las configuraciones sin búsqueda de herramientas incluyen un ANTHROPIC_BASE_URL personalizado, ENABLE_TOOL_SEARCH=false, y un modelo anterior a la generación Claude 4.5 en Google Cloud's Agent Platform.
• En una implementación de Microsoft Foundry alojada en Azure: Claude comienza en la ruta de búsqueda de herramientas en lugar de con WaitForMcpServers, ya que Claude Code descubre el rechazo del lado del servidor solo desde la API. Después de que Claude Code cambie esa implementación a carga anticipada, las herramientas de un servidor que termina de conectarse se vuelven disponibles en la siguiente solicitud de Claude.

Con búsqueda de herramientas habilitada, cuando un servidor termina de conectarse mientras Claude está trabajando, Claude Code lista los nombres de herramientas del servidor a Claude en su siguiente solicitud en el mismo turno. Claude puede entonces buscar y llamar a esas herramientas sin esperar su siguiente mensaje.

Deshabilitar un servidor sin eliminarlo

Alterne un servidor en el panel /mcp para detener que Claude Code se conecte a él sin perder su configuración. Claude Code aún lista el servidor en /mcp, marcado como deshabilitado.

Cuando alterna un servidor, Claude Code registra su elección por proyecto en ~/.claude.json, en una de dos listas que cubren conjuntos disjuntos de servidores:

• disabledMcpServers: una lista de exclusión para servidores configurados por el usuario, servidores de plugins, los conectores de claude.ai que Claude Code obtiene por sí mismo, servidores que su organización proporciona a través de configuración gestionada, y servidores integrados que están habilitados de forma predeterminada. Claude Code no se conecta a un servidor que lista aquí. Cuando deshabilita un conector de claude.ai con el alternador /mcp por proyecto descrito en Deshabilitar conectores de claude.ai, Claude Code lo escribe en esta lista bajo su nombre de visualización, por ejemplo claude.ai Slack.
• enabledMcpServers: una lista de inclusión para servidores integrados que están deshabilitados de forma predeterminada, como computer-use. Claude Code se conecta a un servidor deshabilitado de forma predeterminada solo cuando lo lista aquí.

Claude Code consulta exactamente una de las dos listas para cada servidor, por lo que ninguna lista anula la otra. Si agrega un servidor regular a enabledMcpServers, o un servidor integrado deshabilitado de forma predeterminada a disabledMcpServers, Claude Code ignora la entrada.

disabledMcpServers y enabledMcpServers no están relacionados con enabledMcpjsonServers y disabledMcpjsonServers, que controlan la aprobación de servidores definidos en el archivo .mcp.json de un proyecto.

Tiempos de ejecución del cliente MCP

Claude Code se conecta a servidores MCP a través de uno de dos tiempos de ejecución del cliente. El tiempo de ejecución v1 se basa en MCP TypeScript SDK 1.x. El tiempo de ejecución v2 es el mismo código en MCP TypeScript SDK 2.0, que añade la revisión del protocolo MCP 2026-07-28. El resto de esta página se aplica a ambos tiempos de ejecución, excepto donde una sección nombra el tiempo de ejecución v2.

En Claude Code v2.1.232 o posterior, Claude Code usa el tiempo de ejecución v2. Elige un tiempo de ejecución cada vez que lo inicia y lo mantiene hasta que sale. Usa v1 cuando lo ejecuta:

• En Amazon Bedrock, Claude Platform en AWS, Google Cloud's Agent Platform, o Microsoft Foundry, a menos que una plataforma host que incrusta Claude Code establezca CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
• Iniciado sesión a través de una puerta de enlace de aplicaciones Claude
• Con obtención de banderas de características desactivada

En v2, Claude Code también:

• Pregunta a servidores HTTP y conectores de claude.ai si admiten la revisión más nueva, y la usa con los que lo hacen. Solo pregunta a servidores stdio si establece MCP_PROTOCOL_NEGOTIATION en auto, y se conecta a todos los demás servidores como v1 lo hace.
• Recibe notificaciones list_changed de servidores en la revisión más nueva sobre una secuencia que mantiene abierta.
• No registra un servidor de canal que se conecta en la revisión más nueva, porque esa revisión no puede llevar mensajes de canal.
• Falla un inicio de sesión OAuth de MCP cuya respuesta de autorización nombra un emisor inesperado.

Anthropic puede mantener un servidor específico en el protocolo anterior, u off esa secuencia, con una bandera de característica que Claude Code obtiene.

Para elegir el tiempo de ejecución usted mismo, establezca MCP_SDK_GENERATION en v1 o v2. Para decidir si Claude Code pregunta, establezca MCP_PROTOCOL_NEGOTIATION en auto o legacy. Donde Claude Code usa v1 de forma predeterminada, fijar v2 no hace que pregunte, por lo que establezca auto también.

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.

Si una solicitud de actualización falla, Claude Code mantiene las herramientas, indicaciones y recursos descubiertos anteriormente del servidor hasta que una actualización posterior tenga éxito. Antes de v2.1.214, un error transitorio durante la actualización reemplazaba las herramientas, indicaciones y recursos del servidor con una lista vacía.

Secuencias de notificación en el tiempo de ejecución v2

En el tiempo de ejecución v2, Claude Code recibe notificaciones list_changed de un servidor en la revisión del protocolo más nueva sobre una secuencia que mantiene abierta. Cuando la secuencia se cierra, Claude Code la reabre, con dos límites:

• La secuencia se cierra nuevamente dentro de 10 segundos: Claude Code la reabre hasta tres veces, luego se detiene para esa conexión.
• La secuencia permanece abierta más de 10 segundos, luego se cierra, como las secuencias a hosts sin servidor comúnmente lo hacen: después de cinco reaperturas en una hora, Claude Code espera aproximadamente seis horas antes de la siguiente.

Hasta que la secuencia se reabre, mantiene las herramientas, indicaciones y recursos obtenidos por última vez del servidor. Para recoger sus cambios más pronto, reconecte el servidor desde /mcp.

Reconexión automática

Claude Code reconecta un servidor remoto que se cae a mitad de sesión y reintenta la primera conexión de un servidor HTTP o SSE después de un error transitorio. Los servidores stdio son procesos locales, y Claude Code no los reconecta automáticamente.

Caídas a mitad de sesión de un servidor remoto

Claude Code reconecta un servidor remoto caído con retroceso exponencial: hasta cinco intentos, comenzando con un retraso de un segundo y duplicándolo cada vez. Lo que ve depende de cómo esté ejecutando Claude Code:

• En una sesión interactiva: /mcp muestra el servidor como pendiente mientras Claude Code se reconecta. Después de cinco intentos fallidos, Claude Code marca el servidor como fallido, o como necesitando autenticación cuando el servidor necesita autorización nuevamente. Puede reintentar manualmente desde /mcp.
• En ejecuciones claude -p y sesiones Agent SDK: Claude Code se reconecta en el mismo cronograma, sin panel /mcp para mostrar los intentos.

Fallos de primera conexión

Cuando la primera conexión de un servidor HTTP o SSE falla con un error transitorio, como una respuesta 5xx, una conexión rechazada, o un tiempo de espera, Claude Code reintenta hasta tres veces. Si la conexión aún falla, Claude Code marca el servidor como fallido. Claude Code reintenta de esta manera al inicio y cuando se agrega un servidor a mitad de sesión. Eso incluye un servidor que Claude Code agrega a una sesión en la nube desde su configuración y un servidor que agrega con el setMcpServers() del Agent SDK.

Claude Code no reintenta en estos casos:

• Primera conexión de un servidor WebSocket
• Un error de autenticación o no encontrado, porque requiere un cambio de configuración para resolverse. Cuando un headersHelper es la única fuente del servidor del encabezado Authorization, Claude Code reintenta un error de autenticación de todas formas, porque vuelve a ejecutar el helper en cada intento y puede recoger una credencial fresca

Solicitudes de descubrimiento fallidas

Después de que un servidor se conecta, Claude Code le envía solicitudes de descubrimiento de capacidades como tools/list, prompts/list, y resources/list. Claude Code reintenta esas solicitudes hasta tres veces con retroceso corto después de un error de red o servidor transitorio. No reintenta errores de autenticación, respuestas 4xx, o tiempos de espera de solicitud.

Cómo Claude aprende que un servidor falló

Si Claude Code le dice a Claude sobre un servidor configurado que falló al conectarse depende de búsqueda de herramientas, que está habilitada de forma predeterminada:

• Con búsqueda de herramientas, Claude Code le dice a Claude qué servidor falló y su error de conexión, por lo que Claude informa el fallo de conexión en su respuesta. Claude Code incluye la misma información en resultados de ToolSearch que no encuentran ninguna herramienta coincidente.
• En cualquier configuración sin búsqueda de herramientas, Claude Code no informa fallos de conexión de servidores configurados a Claude.

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.

En el tiempo de ejecución v2, si establece MCP_PROTOCOL_NEGOTIATION en auto y un servidor de canal negocia la revisión del protocolo MCP 2026-07-28, no puede entregar mensajes de canal, por lo que Claude Code no lo registra como un canal. Dejar la variable sin establecer, o establecerla en legacy, mantiene los servidores stdio en el apretón de manos anterior.

El timeout por servidor es un límite de reloj de pared duro por llamada de herramienta, y las notificaciones de progreso del servidor no lo extienden. Los valores por debajo de 1000 se ignoran y caen a MCP_TOOL_TIMEOUT, o a su predeterminado de aproximadamente 28 horas cuando esa variable no está establecida. Para un servidor HTTP, SSE, o conector de claude.ai también hay un segundo temporizador por solicitud que cubre cada solicitud hasta el primer byte de respuesta del servidor. Claude Code establece ese temporizador al mayor de tres valores: 60 segundos, el tiempo de espera de herramienta que se aplica al servidor, y MCP_TIMEOUT. El predeterminado de 28 horas de un MCP_TOOL_TIMEOUT no establecido no entra en esa comparación, y un valor por debajo de 60 segundos no acorta el temporizador. Los servidores stdio y WebSocket no tienen temporizador por solicitud.

Un timeout por servidor de al menos 1000 también actúa como un piso en el tiempo de espera de inactividad descrito a continuación: Claude Code nunca cancela las llamadas de herramientas de ese servidor por inactividad antes que el timeout por servidor. Requiere Claude Code v2.1.203 o posterior.

Una llamada de herramienta a un servidor MCP que no envía respuesta ni notificación de progreso durante la ventana de inactividad se cancela con un error en lugar de esperar el límite de reloj de pared. El tiempo de espera de inactividad requiere Claude Code v2.1.187 o posterior. Se aplica a todos los tipos de servidor excepto servidores IDE y servidores en proceso SDK. La ventana de inactividad predeterminada es de cinco minutos para servidores HTTP, SSE, WebSocket y conector de claude.ai, y de 30 minutos para servidores stdio. Antes de v2.1.203, los servidores stdio estaban exentos del tiempo de espera de inactividad.

Establezca la variable de entorno CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT en milisegundos para cambiar la ventana de inactividad, o establézcala en 0 para desactivar la verificación.

Estos tiempos de espera limitan cuánto tiempo puede ejecutarse una llamada, no siempre cuánto tiempo bloquea la sesión: una llamada de conversación principal que se ejecuta más de dos minutos se mueve a una tarea de fondo primero. Vea Backgrounding automático de llamadas de herramientas largas.

Backgrounding automático de llamadas de herramientas largas

Una llamada de herramienta MCP en la conversación principal que aún se está ejecutando después de dos minutos se mueve a una tarea de fondo en lugar de bloquear la sesión. Claude recibe el ID de tarea inmediatamente y continúa trabajando, y el resultado llega como una notificación de tarea cuando la llamada se resuelve. El backgrounding automático requiere Claude Code v2.1.212 o posterior.

La tarea aparece en /tasks, donde también puede detenerla, y no sobrevive a salir de la sesión. Los límites por llamada aún se aplican mientras la llamada se ejecuta en segundo plano: el límite de reloj de pared establecido por el timeout por servidor o MCP_TOOL_TIMEOUT, y el tiempo de espera de inactividad establecido por CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT.

Establezca la variable de entorno CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS en milisegundos para cambiar el umbral, o establézcala en 0 para desactivar el backgrounding automático. Establecer CLAUDE_CODE_DISABLE_BACKGROUND_TASKS en 1 también lo desactiva, junto con todas las otras características de tareas de fondo.

Algunas llamadas nunca se mueven al fondo:

• Llamadas de subagentes; Claude Code solo coloca en segundo plano llamadas de conversación principal
• Llamadas a servidores IDE
• Llamadas en modo no interactivo, a menos que CLAUDE_AUTO_BACKGROUND_TASKS esté establecido en 1, ya que una ejecución de una sola vez puede terminar antes de que llegue el resultado

Una llamada esperando un diálogo de elicitación abierto no se coloca en segundo plano mientras el diálogo está abierto; el servidor está bloqueado en su entrada, no es lento, por lo que Claude Code difiere el movimiento hasta que el diálogo se cierre.

Servidores MCP proporcionados por plugins

Los plugins pueden agrupar servidores MCP que proporcionan herramientas e integraciones cuando habilita el plugin. 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 habilita un plugin, Claude Code inicia sus servidores MCP automáticamente
• Claude Code ofrece herramientas MCP de plugins junto a herramientas MCP configuradas manualmente
• Agrega y elimina servidores de plugins instalando o desinstalando el plugin, no con comandos /mcp. Aún puede alternar un servidor de plugin instalado en /mcp, que detiene que Claude Code se conecte a él sin eliminar el plugin

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: los servidores se conectan y desconectan en estos puntos:
  • Al inicio de la sesión, Claude Code conecta automáticamente los servidores para plugins habilitados. En /mcp, un servidor de plugin remoto (HTTP o SSE) que ha usado antes puede mostrar el estado cached en su lugar; Claude Code lo conecta cuando Claude llama por primera vez a una de sus herramientas
  • Si habilita o deshabilita un plugin durante una sesión, Claude Code conecta o desconecta sus servidores MCP cuando el cambio se aplica. Aplicar cambios de plugins sin reiniciar describe cuándo es eso. En una sesión sin una terminal interactiva, /reload-plugins no conecta ni desconecta servidores MCP de plugins; esos cambios tienen efecto en su próxima sesión
  • Cuando recarga, Claude Code mantiene las conexiones activas de servidores de plugins cuya configuración no ha cambiado, y hace lo mismo cuando reemplaza la lista de servidores MCP de la sesión desde el Agent SDK sin nombrarlos
  • Cuando mueve la sesión con /cd en v2.1.246 o posterior, Claude Code conecta los servidores de plugins que la configuración del nuevo directorio habilita y desconecta los servidores de plugins que ya no están habilitados, por lo que no necesita ejecutar /reload-plugins después del movimiento
  • En sesiones web, una llamada MCP a un servidor de plugin que aún no está conectado, como justo después de que una sesión inactiva se despierte, inicia el servidor bajo demanda y espera a que se conecte
• Marcadores de posición de ruta: ${CLAUDE_PLUGIN_ROOT} se resuelve al directorio de instalación del plugin, ${CLAUDE_PLUGIN_DATA} a su directorio de estado persistente, y ${CLAUDE_PROJECT_DIR} a la raíz del proyecto estable. La sustitución se aplica a:
  • servidores stdio: command, args, env
  • servidores http, sse y ws: url, headers y headersHelper. Antes de v2.1.195, headersHelper pasaba el marcador de posición como una cadena literal
• 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, HTTP y WebSocket, aunque el soporte de transporte puede variar según el servidor

Los servidores de plugins aparecen en /mcp con indicadores que muestran que provienen de plugins.

Nombres de herramientas MCP de plugins:

Las herramientas de un servidor MCP agrupado en un plugin incluyen tanto el nombre del plugin como la clave del servidor en su nombre invocable. La forma completa es mcp__plugin_<plugin-name>_<server-name>__<tool-name>, donde cualquier carácter fuera de A-Z, a-z, 0-9, _ y - se reemplaza con _. Para el servidor database-tools agrupado en un plugin llamado my-plugin, una herramienta query es invocable como:

mcp__plugin_my-plugin_database-tools__query

Use este nombre completo cuando haga referencia a la herramienta en reglas de permisos, la lista allowed-tools de una skill, un campo tools de un subagente, o un matcher de hook. Un matcher de hook escrito contra la clave del servidor simple, como mcp__database-tools__.*, nunca se activa para un servidor agrupado en un plugin.

El servidor mismo se registra bajo el nombre con alcance plugin:<plugin-name>:<server-name>, como plugin:my-plugin:database-tools. Use ese nombre donde se espera un nombre de servidor configurado, como un campo server del hook mcp_tool.

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 o proporcionar servidores para cada usuario 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. Cuando agrega un servidor con alcance de proyecto, Claude Code crea o actualiza automáticamente este archivo con la estructura de configuración apropiada. Verifique .mcp.json en el control de versiones para que todos en su equipo obtengan las mismas herramientas y servicios MCP.

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

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

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Por razones de seguridad, Claude Code solicita aprobación en sesiones interactivas antes de usar servidores con alcance de proyecto desde archivos .mcp.json. Para restablecer esas opciones de aprobación, ejecute claude mcp reset-project-choices.

En ejecuciones de claude -p, sesiones de Agent SDK y sesiones en la nube, Claude Code no puede mostrar ese mensaje: carga servidores con alcance de proyecto sin preguntar. Claude Code también omite el mensaje en una sesión que inicia en modo bypassPermissions con skipDangerousModePermissionPrompt establecido en su configuración de usuario o en configuración administrada. Para mantener un servidor fuera de todas formas:

• Agréguelo a disabledMcpjsonServers, que lo bloquea en cada modo de permiso.
• Excluya la configuración del proyecto completamente con --setting-sources o la opción settingSources del SDK.
• Inicie la sesión con --strict-mcp-config. Claude Code entonces usa solo los servidores MCP que pasa con --mcp-config. Omitir el mensaje de aprobación para los servidores con alcance de proyecto que Claude Code no está cargando requiere Claude Code v2.1.246 o posterior; antes de v2.1.246, una sesión estricta aún esperaba aprobación para ellos, lo que dejaba las sesiones en segundo plano esperando al inicio. Vea Control exclusivo con managed-mcp.json para lo que hace la bandera bajo un archivo MCP administrado.

Aprobaciones de servidor de proyecto y confianza del espacio de trabajo cubre cómo las aprobaciones confirmadas en el repositorio interactúan con la confianza del espacio de trabajo.

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. La entrada completa del servidor de esa fuente se utiliza; los campos no se fusionan entre alcances.

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.

Un servidor que su organización proporciona a través de la configuración administrada managedMcpServers se clasifica por encima de todos estos, por lo que cuando uno de ellos lo duplica, Claude Code conecta la definición de la organización. Requiere Claude Code v2.1.259 o posterior.

Si abre una sesión local en la pestaña Code de la aplicación de escritorio con el mismo nombre de servidor stdio en el nivel superior de ~/.claude.json (alcance de usuario) y en .mcp.json, la pestaña Code usa la definición de ~/.claude.json.

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 referenciada no está establecida y no tiene un valor predeterminado, la configuración aún se carga: Claude Code informa una advertencia de variable faltante para ese servidor en la salida de claude mcp list y usa el texto ${VAR} sin expandir tal como está. Establezca la variable o agregue un fallback :-default para que el servidor se inicie con el valor que pretende.

Ejemplos prácticos

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"

Reemplace YOUR_GITHUB_PAT con su token de acceso personal. El comando claude mcp add guarda la configuración sin validar credenciales, por lo que se acepta un valor de marcador de posición aquí pero el servidor no se conecta más tarde. Para verificar la conexión, ejecute /mcp y compruebe que el servidor muestre connected. Un servidor con credenciales incorrectas muestra failed, y el detalle de fallo incluye el estado HTTP que devolvió el servidor, como un 401.

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

DBHub, el paquete @bytebase/dbhub, es un servidor MCP que conecta Claude a una base de datos relacional a través de la cadena de conexión que pasa en --dsn. Use un usuario de base de datos de solo lectura en la cadena de conexión para que las consultas que ejecuta Claude no puedan modificar datos:

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

Para confirmar que el servidor se inicia, ejecute /mcp y compruebe que db muestre connected.

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 Code marca un servidor remoto como que requiere autenticación cuando el servidor responde con 401 Unauthorized o 403 Forbidden. Lo que Claude Code muestra depende del servidor:

• Para un servidor en el que no ha iniciado sesión, cualquiera de estos códigos de estado lo marca en /mcp para que pueda completar el flujo de OAuth.
• Para un conector de claude.ai, un 401 causado por claude.ai rechazando su token de sesión no marca el conector, porque reautorizar el conector no puede solucionar su inicio de sesión. Claude Code muestra el estado de token de sesión rechazado en su lugar.
• Para un servidor cuyo encabezado Authorization configuró, en headers o a través de un headersHelper, un 401 o 403 mientras se conecta no marca el servidor, porque la credencial a corregir es la que configuró. Claude Code reporta la conexión como fallida en su lugar.
• Para un conector entregado a una sesión en la nube, Claude Code no ejecuta un flujo de inicio de sesión, porque el proxy de la sesión se autentica con el conector con la autorización que otorgó en claude.ai. Cuando un conector allí necesita autorización nuevamente, reconéctelo en claude.ai/customize/connectors en lugar de desde la sesión.

Cuando una solicitud a un servidor OAuth en el que ya ha iniciado sesión devuelve 401 Unauthorized, Claude Code actualiza el token almacenado, se reconecta e intenta la solicitud una vez más. Solo marca el servidor en /mcp si ese reintento también falla. Antes de v2.1.206, una actualización de token que falló por una razón transitoria, como un error de red, marcaba un servidor OAuth como que necesitaba autenticación durante el resto de la sesión aunque su token de actualización seguía siendo válido.

Cuando el servidor rechaza el token de actualización almacenado, Claude Code muestra inmediatamente un aviso que apunta a /mcp. Abra /mcp y seleccione Re-authenticate en el servidor para iniciar sesión nuevamente antes de que la siguiente llamada de herramienta falle.

Un servidor personalizado que devuelve un encabezado WWW-Authenticate que apunta a su servidor de autorización obtiene el mismo descubrimiento automático que cualquier otro servidor remoto.

Claude Code también muestra un aviso de inicio cuando uno o más servidores configurados necesitan autenticación, por lo que no tiene que abrir /mcp para descubrir qué servidores necesitan iniciar sesión. El aviso requiere Claude Code v2.1.193 o posterior. Solo cuenta servidores en los que puede iniciar sesión desde Claude Code. Antes de v2.1.218, también contaba conectores de claude.ai que no estaban conectados en claude.ai, que solo puede conectar desde la configuración de claude.ai.

En modo no interactivo no hay panel /mcp, por lo que Claude Code no puede ejecutar el flujo de OAuth para usted. A partir de v2.1.196, cuando un servidor configurado necesita autenticación durante una ejecución de claude -p o Agent SDK con búsqueda de herramientas habilitada, que es la predeterminada, Claude Code le dice a Claude que las herramientas del servidor no están disponibles hasta que lo autorice. Claude puede entonces nombrar el servidor que necesita iniciar sesión en lugar de responder como si el servidor no estuviera configurado. Complete el inicio de sesión desde una sesión interactiva con /mcp o claude mcp login <name>.

Si configuró headers.Authorization para el servidor y el servidor rechaza ese encabezado, Claude Code reporta la conexión como fallida en lugar de recurrir a OAuth. Verifique que el token sea válido para el punto final de MCP, o elimine el encabezado para usar el flujo de OAuth.

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

/mcp

Autenticarse desde la línea de comandos

A partir de v2.1.186, claude mcp login <name> ejecuta el flujo de OAuth de un servidor configurado directamente desde su shell, por lo que no necesita abrir el panel /mcp dentro de una sesión.

claude mcp login sentry

Para borrar las credenciales almacenadas más tarde, ejecute claude mcp logout <name>.

A partir de v2.1.191, el comando detecta cuando no hay navegador local disponible, como durante una sesión SSH o en Linux sin un servidor de pantalla, e imprime la URL de autorización en lugar de intentar abrir un navegador. Abra la URL en su máquina local, luego pegue la URL de redireccionamiento completa de la barra de direcciones de su navegador nuevamente en el indicador. El comando necesita una terminal interactiva para el paso de pegado, así que conéctese con ssh -t. Pase --no-browser para forzar el indicador de URL incluso cuando se detecta un navegador local.

claude mcp login sentry --no-browser

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. Si el inicio de sesión en Claude Code v2.1.229 falla con un error de desajuste de URI de redireccionamiento, consulte la nota de versión en Usar credenciales OAuth preconfiguradas.

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. Establezca authServerMetadataUrl cuando los puntos finales estándar del servidor MCP generen errores, o cuando desee enrutar el descubrimiento a través de un proxy interno. 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://. 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.

A partir de v2.1.196, cuando oauth.scopes no está establecido, Claude Code solicita el alcance proporcionado por el encabezado WWW-Authenticate del servidor o sus metadatos de recursos protegidos, y no envía ningún parámetro scope cuando ninguno proporciona uno. Ya no solicita el catálogo completo de scopes_supported de los metadatos del servidor de autorización descubiertos automáticamente. Solicitar ese catálogo hizo que los proveedores de identidad que anuncian alcances solo para administrador o de plantilla rechazaran la solicitud de autorización con un error invalid_scope. Los metadatos obtenidos de un authServerMetadataUrl configurado aún proporcionan su scopes_supported como los 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
• Claude Code ejecuta el comando en un shell y se rinde después de 10 segundos
• Claude Code elige el directorio de trabajo del comando por dónde configuró el servidor, así que proporcione el script como una ruta absoluta o colóquelo en PATH
• Los encabezados dinámicos anulan cualquier headers estático con el mismo nombre

Claude Code ejecuta el ayudante nuevamente en cada conexión, al iniciar la sesión y al reconectar, una vez que la regla de confianza para servidores de alcance de proyecto y local le permite ejecutarse. No almacena en caché el resultado, por lo que su script es responsable de cualquier reutilización de tokens.

Si una llamada de herramienta devuelve 401 Unauthorized o 403 Forbidden, Claude Code automáticamente vuelve a ejecutar el ayudante bajo la misma regla, se reconecta con los encabezados frescos, e intenta la llamada una vez más. Claude Code marca el servidor como que necesita autenticación en /mcp solo si ese reintento también falla.

Cuando la salida del ayudante incluye un encabezado Authorization, Claude Code usa esa credencial como la autenticación del servidor y no recurre a OAuth para el servidor.

Si el servidor rechaza la credencial del ayudante mientras se conecta, Claude Code reporta la conexión como fallida en lugar de marcar el servidor como que necesita autenticación. Corrija la credencial que devuelve su ayudante, luego reconéctese desde /mcp para volver a ejecutar el ayudante.

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.

Un headersHelper proporcionado por un plugin no puede hacer referencia a los valores ${user_config.*} del plugin, porque el comando se ejecuta a través de un shell. Claude Code reporta el servidor como mal configurado con un error y no sustituye el valor. Ponga ${user_config.KEY} en el campo headers del servidor en su lugar, que no se analiza como shell, o haga que el script de ayudante lea el valor de un archivo de configuración. Antes de v2.1.207, headersHelper sustituía valores ${user_config.*}.

Dónde se ejecuta el ayudante

Claude Code elige el directorio de trabajo del comando headersHelper de la configuración que declara el servidor. Un cd que Claude ejecuta en Bash no lo mueve, y /cd lo mueve solo para servidores que se ejecutan desde el directorio de trabajo principal de la sesión. Cada fila a continuación proporciona el directorio contra el cual se resuelve una ruta relativa en su comando headersHelper.

Antes de v2.1.238, Claude Code también ejecutaba los ayudantes de servidores de alcance de usuario, administrados y conectores de claude.ai, y de archivos de agente de fuera de su proyecto, desde el directorio desde el que lo inició.

Qué variables puede leer un ayudante

Un headersHelper que un repositorio o plugin proporciona es un comando que no escribió, por lo que Claude Code lo ejecuta sin las variables de credencial de su entorno, como ANTHROPIC_API_KEY. Dónde configuró el servidor decide si esto se aplica:

• Eliminadas: un servidor en un .mcp.json de proyecto o en un plugin, y un servidor en línea en un archivo de agente de su proyecto o de un directorio --add-dir
• No eliminadas: un servidor en alcance de usuario o alcance local, en MCP administrado, de un conector de claude.ai, o proporcionado por el SDK o --mcp-config, y un servidor en línea en un archivo de agente de ~/.claude/agents/, de configuración administrada, o pasado con --agents

Aparte de las variables GIT_CONFIG_KEY_<n> de Git, Claude Code elimina cada variable de su entorno cuyo nombre se parece a una credencial, como un nombre con TOKEN, SECRET, PASSWORD, KEY, o AUTH en él en cualquier caso de letra, por lo que ANTHROPIC_API_KEY y MY_REGISTRY_TOKEN se eliminan. Claude Code también elimina una lista fija de variables de credencial cuyos nombres no siguen ese patrón, como ANTHROPIC_CUSTOM_HEADERS.

Cuando esto se aplica a su ayudante, haga que el script lea su credencial de un archivo o un almacén de credenciales. Si la url del servidor expande una de estas variables, el valor CLAUDE_CODE_MCP_SERVER_URL que recibe el ayudante tiene esa parte reemplazada con REDACTED también.

Confiar en una carpeta antes de que se ejecute su headersHelper

Claude Code ejecuta un headersHelper como un comando de shell arbitrario. Para un servidor en un .mcp.json de proyecto o en alcance local, lo ejecuta solo después de que acepte el diálogo de confianza para el directorio del proyecto donde se declara el servidor. Antes de v2.1.238, una sesión claude -p o SDK ejecutaba estos ayudantes sin verificar confianza, y una sesión interactiva los ejecutaba una vez que había confiado en una carpeta principal.

• Confianza que no cuenta: la confianza de una carpeta principal, y la confianza automática que una sesión claude -p o SDK obtiene para hooks en archivos de configuración
• Hasta que confíe en la carpeta: Claude Code conecta el servidor solo con sus headers estáticos. En una sesión claude -p o SDK también imprime una línea headersHelper not run por servidor en stderr, diciéndole cómo otorgar la confianza.
• Confianza sin un diálogo: establezca projects["<path>"].hasTrustDialogAccepted en true en ~/.claude.json. <path> es la carpeta en la que Reglas de permiso de proyecto y confianza del espacio de trabajo dice que Claude Code basa la confianza.

Claude Code aplica la misma regla a un servidor declarado en línea en un archivo de agente, verificando de dónde vino ese archivo de agente: su proyecto, para un archivo en su directorio .claude/agents/, o un directorio --add-dir. Hasta que confíe en ese proyecto o directorio mismo, Claude Code no carga el servidor en absoluto, por lo que su ayudante nunca se ejecuta tampoco.

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 

Los nombres de servidores agregados a través de comandos claude mcp pueden contener solo letras, números, guiones y guiones bajos. Claude Desktop no aplica esa restricción, por lo que un servidor de Claude Desktop cuyo nombre contiene cualquier otro carácter, como un espacio, no puede ser importado. La importación reporta cada nombre que rechaza e importa los otros servidores que seleccionó. Antes de v2.1.205, el primer nombre inválido detenía la importación y ninguno de los servidores seleccionados se agregaba.

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 añadido en claude.ai, conocidos como conectores, están disponibles automáticamente en Claude Code:

/mcp

Claude Code marca un conector como managed en /mcp y en el gestor de /plugin cuando su organización gestiona su autenticación en claude.ai. El estado managed no cambia cómo Claude Code se conecta al conector ni aplica los controles de herramientas de su organización.

Los conectores a los que nunca ha iniciado sesión se contraen detrás de una fila Show unused connectors al final de la sección de claude.ai, por lo que una lista provisionada por la organización no llena el panel. Seleccione la fila para expandirlos. Un conector en el que inició sesión antes permanece visible incluso cuando actualmente necesita reautenticación.

Los conectores de claude.ai se obtienen solo cuando su método de autenticación activo es un inicio de sesión de suscripción de claude.ai. No se cargan, incluso si ejecutó /login anteriormente, cuando:

• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, o apiKeyHelper está activo
• Un proveedor de terceros como Amazon Bedrock o Agent Platform de Google Cloud está activo
• ANTHROPIC_PROFILE, las variables de federación, o un perfil de Anthropic activo proporciona la credencial
• CLAUDE_CODE_OAUTH_TOKEN contiene un token de claude setup-token, que solo puede hacer solicitudes de modelo

Si /mcp no enumera un conector que añadió, ejecute /status para confirmar qué método de autenticación está activo. Desactive esa variable de entorno, elimine la configuración apiKeyHelper, o desactive el perfil, luego ejecute /login para seleccionar su cuenta de claude.ai.

Si una red temporal mantiene la lista de conectores sin cargar cuando su sesión comienza, Claude Code reintenta la obtención hasta tres veces en segundo plano, y los conectores aparecen una vez que un reintento tiene éxito. Si aún no han aparecido, reinicie Claude Code para obtener la lista nuevamente.

Si /mcp muestra un conector como connected · session token rejected, o su vista de detalle muestra claude.ai rejected the session token, claude.ai rechazó el token de su inicio de sesión de Claude Code, generalmente porque el inicio de sesión expiró y no se pudo actualizar. Autorizar el conector nuevamente no borra este estado, porque la autorización propia del conector en claude.ai no es lo que fue rechazado. Para borrarlo:

1. Ejecute /login para iniciar sesión nuevamente.
2. Reconecte el conector desde /mcp.

Antes de v2.1.222, Claude Code marcaba los conectores como que necesitaban autenticación, y autorizarlos no lo resolvía.

Un servidor que ha añadido 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.

Algunos conectores alojados por Anthropic, como Microsoft 365, Gmail y Google Calendar, no admiten OAuth local desde Claude Code porque el proveedor de identidad ascendente solo acepta la URL de redirección que claude.ai registró. Cuando un servidor que añadió con claude mcp add o en .mcp.json apunta a uno de estos hosts e inicia sesión en él desde /mcp o con claude mcp login, Claude Code muestra is Anthropic-hosted and doesn't support local OAuth, dirigiéndole a conectar el servicio en claude.ai/customize/connectors en su lugar.

Después de eliminar su entrada con claude mcp remove <name> y conectar el servicio en claude.ai, el conector aparece en Claude Code automáticamente.

Cómo los conectores llegan a Claude Code

Qué configuración rige un conector de claude.ai depende de dónde se ejecute su sesión, porque solo algunas sesiones obtienen conectores de claude.ai por sí mismas. Cada fila a continuación nombra cómo los conectores llegan en un tipo de sesión y qué los controla allí. Las sesiones WSL de la aplicación de escritorio no tienen fila porque los conectores aún no están disponibles en ellas.

disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS, y allowAllClaudeAiMcps actúan solo en la primera fila, los conectores que Claude Code obtiene por sí mismo. Las otras dos filas difieren de ella de estas maneras:

• Sesiones en la nube: Las entradas allowedMcpServers y deniedMcpServers que llegan a la sesión, por ejemplo a través de configuración gestionada por servidor, también filtran los conectores entregados. El proxy de la sesión reescribe la URL de cada conector, por lo que un patrón serverUrl escrito para la URL propia del conector no coincide con él. Para admitir conectores entregados junto con una lista de permitidos de URL en un entorno autohospedado, añada las entradas serverUrl enumeradas en El tráfico de conectores sale de su red. Claude Code descarta los conectores entregados cuando hay un managed-mcp.json presente en el host que ejecuta la sesión, como un host de ejecutor autohospedado, independientemente de si establece allowAllClaudeAiMcps.
• Sesiones locales y SSH de la aplicación de escritorio: la aplicación de escritorio registra los conectores como servidores type: "sdk" en proceso, y ninguna configuración MCP o managed-mcp.json llega a ellos. Un usuario mantiene un conector fuera de sus propias sesiones desconectándolo en claude.ai/customize/connectors. Una organización bloquea las herramientas de un conector o desactiva Claude Code en la aplicación de escritorio completamente.

Controles de organización en herramientas de conector

Su organización puede establecer controles por herramienta en conectores de claude.ai. Claude Code lee esta configuración al iniciar y la aplica localmente, excepto en las sesiones locales y SSH de la aplicación de escritorio. Allí, la aplicación de escritorio retiene las herramientas blocked antes de entregar un conector, y la configuración ask no llega a Claude Code, por lo que aplica las reglas de permiso ordinarias de la sesión a esas herramientas en lugar de solicitar en cada llamada. En sesiones donde Claude Code obtiene conectores por sí mismo, ejecute /mcp para ver qué configuración se aplica a cada herramienta en un conector.

• Herramienta establecida en ask: Claude Code solicita en cada llamada con la razón Your organization requires approval for this tool. La solicitud aparece incluso en los modos de permiso acceptEdits, auto, y bypassPermissions, y nunca ofrece una opción para recordar su elección. Las reglas de permitir que coinciden con la herramienta tampoco omiten la solicitud. En modo dontAsk, que nunca solicita, Claude Code niega la llamada en su lugar.
• Herramienta establecida en blocked: Claude Code filtra la herramienta antes de que Claude la vea, por lo que nunca aparece en la lista de herramientas. La aplicación de escritorio y el chat de claude.ai aplican la misma configuración blocked, por lo que Claude tampoco puede usar la herramienta allí, y no puede retener una herramienta de las sesiones de la aplicación de escritorio mientras la mantiene disponible en el chat. La aplicación de escritorio omite un conector cuyas herramientas están todas bloqueadas.

Desactivar conectores de claude.ai

Claude Code aplica disableClaudeAiConnectors solo a los conectores que obtiene por sí mismo, no a los conectores que entrega un host en la nube o la aplicación de escritorio. Para desactivar los conectores que obtiene, establezca la configuración en true en cualquier ámbito de configuración:

{
  "disableClaudeAiConnectors": true
}

Esta configuración utiliza semántica any-source-true: true en cualquier fuente de configuración tiene precedencia. Un .claude/settings.json de proyecto verificado puede optar por que un repositorio no use los conectores que Claude Code obtiene por sí mismo, pero un false a nivel de proyecto no puede reactivar los conectores que un true a nivel de usuario o política ha desactivado. Los servidores pasados explícitamente a través de --mcp-config no se ven afectados.

También puede establecer la variable de entorno ENABLE_CLAUDEAI_MCP_SERVERS en false, que tiene el mismo efecto para la sesión de shell actual:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Para bloquear conectores individuales de claude.ai en lugar de todos ellos, añádalos a deniedMcpServers por nombre o por patrón de URL. Por ejemplo, una entrada serverName de "claude.ai Slack" bloquea el conector de Slack. También puede ejecutar /mcp para activar o desactivar cualquier conector que Claude Code obtiene solo para el proyecto actual.

Usar Claude Code como servidor MCP

Puede usar Claude Code como servidor MCP que otras aplicaciones pueden conectar:

# Inicia Claude como servidor MCP stdio
claude mcp serve

El comando no imprime nada cuando se inicia. Un servidor MCP stdio se comunica a través de stdin y stdout, por lo que una terminal silenciosa y bloqueada significa que el servidor está ejecutándose y esperando que un cliente se conecte.

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 de MCP producen salidas grandes, Claude Code ayuda a gestionar el uso de tokens para evitar sobrecargar el contexto de su conversación:

• Umbral de advertencia de salida: Claude Code muestra una advertencia cuando la salida de cualquier herramienta de MCP excede 10,000 tokens
• Límite configurable: puede ajustar el máximo de tokens de salida de MCP 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é configurado. Las herramientas que devuelven datos de imagen siguen estando sujetas a MAX_MCP_OUTPUT_TOKENS
• Superando el límite: cuando un resultado sin contenido de imagen excede el límite, Claude Code lo guarda en un archivo y lo reemplaza en la conversación con un mensaje que nombra la ruta del archivo, para que Claude lea el archivo cuando necesite el contenido. El archivo se encuentra en el directorio tool-results de la sesión bajo ~/.claude/projects/.

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

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Aumentar el límite para una herramienta específica

Si está creando un servidor de 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 respuesta tools/list de la herramienta. Claude Code eleva 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 elevar la variable de entorno para herramientas que la declaran. Las herramientas que devuelven datos de imagen siguen estando sujetas al límite de tokens.

Esquemas de entrada de herramientas con un combinador a nivel raíz

Algunos servidores MCP declaran el esquema de entrada de una herramienta como una unión de JSON Schema, con anyOf, oneOf o allOf en el nivel superior del esquema. La API de Claude no acepta esas palabras clave en la raíz del esquema. Sí acepta combinadores anidados dentro de properties, que Claude Code envía sin cambios.

Las herramientas con un combinador a nivel raíz permanecen disponibles. Antes de enviar la herramienta a la API, Claude Code aplana el esquema en un único objeto y antepone una oración a la descripción de la herramienta que le indica a Claude qué grupos de parámetros pertenecen juntos:

• allOf: las propiedades de cada rama se fusionan, y la lista required de cada rama sigue aplicándose
• anyOf y oneOf: las propiedades de cada rama se fusionan, y la lista required de cada rama se describe en la descripción de la herramienta en lugar de ser aplicada por el esquema

Su servidor recibe los argumentos que Claude eligió, así que continúe validando la combinación del lado del servidor.

Cuando Claude Code no puede producir un esquema que la API acepte, o en una implementación que no recibe la configuración remota que habilita la reescritura, omite esa herramienta, registra el motivo en el registro del servidor y deja disponibles las otras herramientas del servidor. Las versiones anteriores a v2.1.195 omiten todas las herramientas cuyo esquema de entrada tiene un anyOf, oneOf o allOf a nivel raíz.

Herramientas con esquemas de entrada inválidos

La API de Claude verifica el esquema de entrada de cada herramienta en una solicitud y rechaza toda la solicitud cuando algún esquema falla, por lo que una única herramienta MCP con un esquema malformado haría que todas las solicitudes que la incluyan fallen con un error 400. Claude Code ejecuta dos de las comprobaciones de la API por sí mismo cuando carga las herramientas de un servidor y excluye cada herramienta que fallaría en ellas, de modo que las otras herramientas del servidor sigan funcionando:

• Los nombres de propiedades de nivel superior deben tener entre 1 y 64 caracteres de largo y usar solo letras ASCII y dígitos, _, . y -
• El esquema debe ser válido contra el meta-esquema de JSON Schema draft 2020-12. Claude Code aplica esta comprobación a esquemas que no declaran $schema y esquemas que declaran draft 2020-12. Un esquema que declara cualquier otro dialecto omite esta comprobación, aunque la comprobación de nombres de propiedades anterior sigue aplicándose

Claude Code ejecuta las comprobaciones después de la reescritura de combinador de nivel raíz, en el esquema que realmente enviaría.

Cuando Claude Code excluye una herramienta, registra el motivo en el registro del servidor e indica a Claude qué herramientas excluyó y por qué, para que pueda preguntarle a Claude por qué falta una herramienta. Si corrige el esquema en el servidor, la herramienta reaparece la próxima vez que Claude Code carga las herramientas del servidor.

Claude Code activa la exclusión a través de una bandera de características que obtiene de Anthropic. En una implementación donde la obtención de banderas está desactivada, o en una máquina cuyas banderas nunca han llegado, como una máquina aislada, Claude Code sigue ejecutando las comprobaciones y registra en el registro del servidor qué herramienta sería rechazada, pero envía el esquema de la herramienta a la API de todas formas. La API rechaza una solicitud que incluya ese esquema con un error 400 que nombra la herramienta por su posición. Antes de v2.1.216, ninguna implementación ejecutaba estas comprobaciones.

El manejo de combinador de nivel raíz es independiente y mantiene su propio comportamiento cuando la obtención de banderas está desactivada o las banderas nunca han llegado.

Requerir aprobación para una herramienta específica

Si está construyendo un servidor MCP, puede marcar una herramienta como que requiere aprobación explícita en cada llamada estableciendo _meta["anthropic/requiresUserInteraction"] en true en la entrada de respuesta tools/list de la herramienta. El valor debe ser el booleano JSON true; cualquier otro valor se ignora.

Claude Code muestra el aviso de permiso de esa herramienta en cada llamada, incluso en los modos de permiso acceptEdits, auto y bypassPermissions, y no ofrece una opción "no volver a preguntar" para ella. Las reglas de permiso que coinciden con la herramienta tampoco omiten el aviso. En modo dontAsk, que nunca solicita confirmación, Claude Code deniega la llamada en su lugar.

El aviso tiene que llegar a una persona. En modo no interactivo con --permission-prompt-tool, un resultado allow de la herramienta de aviso de permiso para una herramienta marcada se convierte en una denegación con el mensaje MCP tool requires user interaction; not supported via --permission-prompt-tool. La devolución de llamada canUseTool del Agent SDK sí recibe estas llamadas y puede aprobarlas, porque se espera que su aplicación SDK muestre estas llamadas a un usuario.

Utilice esto para herramientas cuyo aviso de permiso es en sí el punto, como un paso de consentimiento o concesión de acceso donde la aprobación automática significaría que ningún humano nunca estuvo de acuerdo. Otras herramientas del mismo servidor mantienen su comportamiento de permiso normal.

La siguiente entrada tools/list marca una herramienta como que siempre requiere aprobación.

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

La anotación anthropic/requiresUserInteraction requiere Claude Code v2.1.199 o posterior. Las versiones anteriores la ignoran y aplican el flujo de permiso estándar.

Algunas superficies, como Remote Control y aplicaciones construidas en el Agent SDK, normalmente le permiten aprobar llamadas de herramientas con un toque. Para una herramienta marcada con esta anotación, Claude Code retiene la acción de un toque y muestra el aviso de permiso completo de la herramienta en su lugar, por lo que la aprobación sigue viniendo de una persona respondiendo al aviso en lugar de un toque.

Claude Code retiene la aprobación de un toque de la misma manera para cualquier solicitud de permiso que solo el diálogo de terminal pueda renderizar completamente, como una que lleva una advertencia de seguridad u una opción de permitir siempre que la superficie remota no puede mostrar. Usted responde esa solicitud en el diálogo de terminal en lugar de desde Remote Control. Requiere Claude Code v2.1.214 o posterior.

Responder a solicitudes de elicitación de MCP

Los servidores MCP pueden solicitar información estructurada de su parte durante una tarea mediante elicitación. Cuando un servidor necesita información que no puede obtener por sí solo, Claude Code muestra un diálogo interactivo y devuelve su respuesta 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 información de dos formas:

• Modo de formulario: Claude Code muestra un diálogo con campos de formulario definidos por el servidor (por ejemplo, una solicitud 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 y luego confirme en la CLI.

En modo de URL, Claude Code pasa la URL como argumento de línea de comandos al controlador de URL de su sistema y limita la longitud de ese argumento. Cuando la URL, una vez escapada para la línea de comandos, supera ese límite, solo puede rechazar la solicitud. Cada carácter que necesita escaparse, como % o &, cuenta cuatro veces hacia el límite: su propio carácter más tres caracteres de escape. Una URL sin ninguno de ellos alcanza el límite en aproximadamente 8.000 caracteres. Una URL construida en gran medida con escapes de porcentaje, donde cada tercer carácter es un %, lo alcanza en aproximadamente 4.000.

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

Si está creando un servidor MCP que utiliza elicitación, consulte la especificación de elicitación de MCP para obtener detalles del protocolo y ejemplos de esquema.

Usar recursos MCP

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

Referenciar recursos MCP

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

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

Escalar con búsqueda de herramientas MCP

La búsqueda de herramientas mantiene el uso de contexto MCP bajo al diferir las definiciones de herramientas hasta que Claude las necesita. Solo los nombres de herramientas e instrucciones del servidor se cargan al inicio de la sesión, por lo que agregar más servidores MCP tiene un impacto mínimo en su ventana de contexto. Claude Code no impone un límite fijo de herramientas por servidor; el límite práctico es su presupuesto de ventana de contexto.

Para autores de servidores MCP

Si está creando un servidor MCP, el campo de instrucciones del servidor se vuelve más útil con la búsqueda de herramientas habilitada. Las instrucciones del servidor ayudan a Claude a entender cuándo buscar sus herramientas, de manera similar a cómo funcionan las skills.

Agregue instrucciones de servidor claras y descriptivas 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 las descripciones de herramientas e instrucciones del servidor en 2KB cada una. Manténgalas concisas para evitar truncamiento, y coloque los detalles críticos cerca del inicio.

Configurar búsqueda de herramientas

La búsqueda de herramientas está habilitada de forma predeterminada: las herramientas MCP se difieren y se descubren bajo demanda. Claude Code la deshabilita 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 anular ese comportamiento predeterminado.

Configurar CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantiene la búsqueda de herramientas desactivada. No puede anularla configurando ENABLE_TOOL_SEARCH usted mismo. Su organización puede mantener la búsqueda de herramientas activada a través de configuración administrada, en Claude Code v2.1.227 o posterior. Deshabilitar capacidades de pre-lanzamiento cubre dónde se aplica la anulación y qué variable elimina.

La búsqueda de herramientas requiere un modelo que admita bloques tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 y modelos posteriores. Consulte compatibilidad de modelos en la documentación de API para la lista actual.

En Agent Platform de Google Cloud, Claude Code decide por generación de modelo:

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 y posteriores: la búsqueda de herramientas está activada de forma predeterminada, igual que en la API de Anthropic.
• Modelos anteriores de Agent Platform: Claude Code carga todas las herramientas MCP por adelantado, porque sus pilas de servicio rechazan el encabezado beta requerido. ENABLE_TOOL_SEARCH=true no anula esto.

Antes de v2.1.221, Claude Code deshabilitaba la búsqueda de herramientas para todos los modelos en Agent Platform de Google Cloud a menos que configurara ENABLE_TOOL_SEARCH=true.

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

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

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

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

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

Eximir un servidor del diferimiento

Si las herramientas de un servidor siempre deben ser 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 en el contexto al inicio de la sesión independientemente de la configuración ENABLE_TOOL_SEARCH. Úselo para un pequeño número de herramientas que Claude necesita en cada turno, ya que cada herramienta por adelantado 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. 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.

Configurar alwaysLoad: true también hace que el inicio espere las herramientas del servidor, limitado al tiempo de espera de conexión estándar de 5 segundos, ya que deben estar presentes cuando se construye el primer mensaje. Un servidor remoto con una entrada cached válida proporciona sus herramientas desde la caché sin conectarse, por lo que no retiene el inicio. Otros servidores se conectan en segundo plano de forma predeterminada; establezca MCP_CONNECTION_NONBLOCKING=0 para hacer que el inicio también los espere.

Usar prompts de MCP como comandos

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

Ejecutar prompts de MCP

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

Configuración MCP gestionada

Para organizaciones que necesitan control centralizado sobre qué servidores MCP pueden conectar los usuarios, consulte Configuración MCP gestionada. Cubre la implementación de un conjunto de servidores fijo con managed-mcp.json, la provisión de servidores a cada usuario con managedMcpServers, la restricción de servidores con allowedMcpServers y deniedMcpServers, y lo que los usuarios ven cuando un servidor está bloqueado.