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 tus 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 compatible 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"

Al configurar servidores MCP a través de JSON en .mcp.json, ~/.claude.json, o claude mcp add-json, el campo type acepta streamable-http como alias para http. La especificación 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 sin 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.

Solo una aplicación host SDK, como una aplicación Agent SDK o la aplicación de escritorio, puede registrar un servidor "type": "sdk" en proceso. Claude Code omite una entrada "type": "sdk" en .mcp.json, ~/.claude.json, o la configuración e informa Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register.

En ejecuciones --output-format stream-json, Claude Code también informa una entrada --mcp-config omitida en el campo mcp_server_errors del evento system/init, para que los scripts puedan 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 endpoint SSE. Agrégalos 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 conectarte sobre SSE directamente, pasa --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 tu 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, para que tu servidor pueda 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éelo desde dentro de tu 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 estable del proyecto y no cambia cuando agregas o eliminas directorios de trabajo a mitad de 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 roots/list con el directorio de lanzamiento de la sesión más cada directorio de trabajo adicional que hayas otorgado con --add-dir, /add-dir, o el ajuste 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 a través de la expansión ${VAR} en el command o args de una entrada .mcp.json con alcance de proyecto o de una entrada de servidor con alcance local o de usuario en ~/.claude.json 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 que se les solicite. Usa HTTP en su lugar cuando tu servidor solo responda a solicitudes, ya que HTTP admite OAuth y el flag claude mcp add --transport, mientras que WebSocket no admite ninguno de los dos.

Configura 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, así que pasa un token estático en headers o genera uno en el momento de la conexión con headersHelper. El flag 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, busca en esas instrucciones una URL, un comando de lanzamiento, o un bloque JSON:

• 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 tu 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 toman las cuatro opciones en Instalación de servidores MCP. Encuentra a continuación la forma que tienes para convertirla en el comando que Claude Code acepta. Cada comando escribe en alcance local a menos que agregues --scope project o --scope user.

Desde una URL

Una URL significa que el servidor es remoto. Para un endpoint https://, agrégalo con --transport http, o sigue la Opción 2 cuando las instrucciones digan que el endpoint usa SSE. Para un endpoint wss://, usa la 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 de API o un encabezado de token, pásalo con --header como se muestra en la 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. Pon todo el comando después de --, para que Claude Code pase flags como -y al comando que inicia el servidor en lugar de leerlos como sus propias opciones. Pasa cualquier variable de entorno que las instrucciones soliciten 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

La 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, utiliza la clave contenedora y la forma de entrada que Claude Code lee. Pasa a claude mcp add-json el objeto dentro de mcpServers, no el contenedor. Dos tipos de entrada necesitan una reparación primero:

• Una url sin type: agrega "type": "http", "type": "sse", o "type": "ws" para que coincida con el endpoint. 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 y guiones bajos: elige 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 el flag --scope para add-json. Para compartir el servidor con tu equipo en su lugar, agrega --scope project, o agrega la entrada bajo mcpServers en .mcp.json en la raíz de tu proyecto y haz commit. 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 ... en caso de éxito. Para verificar que Claude Code se conectó, ejecuta claude mcp get <name>; Estado del servidor cubre los estados que muestra y el paso de aprobación para servidores .mcp.json.

Administración de tus servidores

Una vez configurados, puedes administrar tus servidores MCP con estos comandos:

# Listar todos los servidores configurados
claude mcp list

# Obtener detalles de 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 eliminas 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 se escribió. Si el comando imprime un mensaje was not saved en su lugar, consulta MCP server was not saved or removed; para un mensaje may not have been saved, consulta MCP server may not have been saved or removed.

claude mcp list muestra un estado de salud junto a cada servidor que enumera, como ✔ Connected, ! Needs authentication, o ✘ Failed to connect. Un estado de falla significa que Claude Code no pudo conectarse a ese servidor, no que el comando de lista 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 de .mcp.json que aún no has aprobado. Claude Code lo muestra tanto en claude mcp list como en claude mcp get <name>. Ejecuta claude de forma interactiva para revisarlo y aprobarlo.
• ✘ 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>. Vuelve a activar el servidor desde el panel /mcp.

Los servidores WebSocket no aparecen en la salida de claude mcp list. Usa 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 de archivos de configuración que no están incluidos en el repositorio, hasta que confíes 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 incluidos con commit en el .claude/settings.json del proyecto se ignoran en una carpeta no confiable, y el servidor permanece en ⏸ Pending approval en lugar de conectarse y verificarse su salud.

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

• tu ~/.claude/settings.json de usuario
• configuración administrada
• configuración pasada con --settings

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

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

Detalle del estado del servidor

En /mcp, incluido el menú de un servidor allí, y en el administrador /plugin, un servidor HTTP o SSE remoto que hayas 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, guardada 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 tu primer mensaje, por lo que no necesitas hacer nada. La caché de descubrimiento y su estado cached requieren Claude Code v2.1.221 o posterior.

La caché de descubrimiento está desactivada de forma predeterminada a menos que un despliegue gradual la haya habilitado para tu cuenta. Establece MCP_DISCOVERY_CACHE=1 para activarla, o 0 para mantenerla desactivada incluso cuando el despliegue la haya habilitado. Antes de v2.1.238, la caché estaba activada de forma predeterminada.

Cuando seleccionas Disable o Clear authentication desde el menú de un servidor en /mcp, Claude Code también descarta la entrada de caché de ese servidor. Reconnect también la descarta en un servidor conectado o fallido; en un servidor cached, Reconnect conecta el servidor de inmediato y mantiene la entrada. La próxima vez que Claude Code se conecte al servidor después de descartar la entrada, obtiene la lista de herramientas del servidor en lugar de la caché.

Cuando el estado de un servidor es ✘ Failed to connect, claude mcp list añade el detalle de la falla a esa línea de estado, y claude mcp get <name> lo muestra en una línea Issue:: el código de estado HTTP o código de error, más cualquier texto de error que el servidor haya devuelto. La vista de detalle del servidor en /mcp incluye el mismo texto informado por el servidor en su fila Issue:. Claude Code oculta de este detalle el texto similar a credenciales y nunca incluye la URL expandida del servidor, 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 falla sin más, sin el código de estado ni el texto de error del servidor.

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

• La ruta y la consulta nunca aparecen en ese mensaje.
• Para un servidor en el alcance local, de proyecto, o de usuario o en la configuración MCP administrada, 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 una falla sin código de estado ni 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 administrador /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 configuras más tarde, por lo que Claude Code no lo informa como un error ni como un problema de configuración. La vista de detalle del servidor en /mcp indica No URL configured for this server; establece la url de la entrada para conectarlo. Antes de v2.1.208, Claude Code informaba una url vacía como un problema de configuración y pedía 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 eliminar 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 un salto de 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 repetir 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, así que edita la configuración para eliminarlo.
• Mismo nombre en más de un alcance: si defines el mismo nombre de servidor en más de un alcance con diferentes endpoints, Claude Code advierte sobre el conflicto en la salida de claude mcp list y en /mcp. Claude Code almacena los inicios de sesión OAuth por endpoint, por lo que cuando autenticas la definición que se carga en un proyecto, aún necesitas iniciar sesión por separado en un proyecto donde se carga una definición diferente. Mantén el endpoint que deseas y elimina los otros con claude mcp remove <name> --scope <scope>. En la advertencia, Claude Code cita el endpoint de cada alcance tal como está escrito en tu configuración, con las referencias ${VAR} sin expandir, por lo que nunca muestra un valor resuelto como una clave de API.
• Nombres reservados: Claude Code reserva los nombres de sus servidores integrados, incluidos workspace, claude-in-chrome, computer-use, Claude Preview, y Claude Browser. Si tu configuración define un servidor con un nombre reservado, Claude Code lo omite en el momento de la carga y muestra una advertencia pidiéndote que lo renombres. claude mcp add rechaza un nombre reservado con un error. Claude Preview y Claude Browser nombran ambos el servidor integrado que utiliza el panel de vista previa de la aplicación de escritorio de Claude Code.
• 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. Establece la variable o agrega un valor de respaldo ${VAR:-default}. En la url y los headers de un servidor remoto, algunas variables de credenciales se leen como vacías en su lugar, sin advertencia.

Disponibilidad de herramientas

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

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

• Con búsqueda de herramientas, el valor predeterminado: la espera sucede 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 Agent Platform de Google Cloud.
• En un despliegue de Microsoft Foundry alojado 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 del despliegue solo desde la API. Después de que Claude Code cambie ese despliegue a carga anticipada, las herramientas de un servidor que termina de conectarse quedan disponibles en la siguiente solicitud de Claude.

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

Después de reanudar una sesión, Claude puede llamar a una herramienta de la conversación guardada mientras el servidor MCP de la herramienta aún se está conectando. Mientras el servidor está en su primer intento de conexión, Claude Code retiene la llamada hasta 10 segundos y la ejecuta en cuanto la herramienta está disponible. Si el servidor no se conecta a tiempo, o ya está reintentando después de un intento fallido, la llamada falla con el error de herramienta No such tool available.

Deshabilitar un servidor sin eliminarlo

Desactiva un servidor en el panel /mcp para que Claude Code deje de conectarse a él sin perder su configuración. Claude Code aún enumera el servidor en /mcp, marcado como deshabilitado.

Cuando activas o desactivas un servidor, Claude Code registra tu 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, servidores que tu organización proporciona a través de la configuración administrada, los conectores de claude.ai que Claude Code obtiene por sí mismo, y servidores integrados que están activados de forma predeterminada. Claude Code no se conecta a un servidor que enumeres aquí. Cuando deshabilitas un conector de claude.ai con el interruptor por proyecto de /mcp descrito en Deshabilitar conectores de claude.ai, Claude Code lo escribe en esta lista bajo su nombre visible, por ejemplo claude.ai Slack.
• enabledMcpServers: una lista de inclusión para servidores integrados que están desactivados de forma predeterminada, como computer-use. Claude Code se conecta a un servidor desactivado de forma predeterminada solo cuando lo enumeras aquí.

Claude Code consulta exactamente una de las dos listas para cada servidor, por lo que ninguna lista sobrescribe a la otra. Si agregas un servidor normal a enabledMcpServers, o un servidor integrado desactivado 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 sobre 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.

Claude Code elige un tiempo de ejecución cada vez que lo inicias y lo mantiene hasta que sales. En sesiones donde obtiene feature flags, utiliza el tiempo de ejecución v2 en Claude Code v2.1.232 o posterior.

En las sesiones donde no obtiene feature flags, Claude Code utiliza el tiempo de ejecución v2 de forma predeterminada en Claude Code v2.1.274 o posterior:

• Sesiones en Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud, o Microsoft Foundry, a menos que una plataforma host que incrusta Claude Code establezca CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
• Sesiones iniciadas a través de un gateway de aplicaciones de Claude
• Sesiones donde desactivas la telemetría o la obtención de feature flags, por ejemplo con DISABLE_TELEMETRY

En v2, Claude Code también:

• Pregunta a los servidores HTTP si admiten la revisión más nueva, y la utiliza con los que la admiten. También pregunta a los servidores de conectores de claude.ai en sesiones donde obtiene feature flags. Para que pregunte a los servidores stdio, o a los servidores de conectores en todas las sesiones, establece MCP_PROTOCOL_NEGOTIATION en auto. Se conecta a todos los demás servidores como lo hace v1.
• Recibe notificaciones list_changed de servidores en la revisión más nueva a través de 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 transportar mensajes de canal.
• Hace fallar un inicio de sesión OAuth de MCP cuya respuesta de autorización nombra un emisor inesperado.
• Envía credenciales de OAuth de MCP solo a un endpoint de token servido sobre HTTPS o en localhost, 127.0.0.1, o ::1. El inicio de sesión falla para un servidor cuyo endpoint de token es http:// simple en cualquier otro lugar, como un dispositivo en tu red local. Consulta Refusing to send credentials to non-https token endpoint.

Anthropic puede mantener un servidor específico en el protocolo anterior, o fuera de esa secuencia, con un feature flag que Claude Code obtiene.

Para elegir el tiempo de ejecución tú mismo, establece MCP_SDK_GENERATION en v1 o v2. Para decidir si Claude Code pregunta, establece MCP_PROTOCOL_NEGOTIATION en auto o legacy.

Actualizaciones dinámicas de herramientas

Un servidor MCP puede cambiar las herramientas, prompts o recursos que ofrece mientras está conectado y enviar una notificación list_changed. Cuando llega una:

• En una sesión interactiva de terminal, Claude Code obtiene la lista actualizada de ese servidor, por lo que no necesitas reconectarlo.
• En modo no interactivo con el flag -p y en el Agent SDK, Claude Code actualiza solo la lista de herramientas con estas notificaciones.

Si una solicitud de actualización falla, Claude Code mantiene las herramientas, prompts 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, prompts 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 más nueva del protocolo a través de 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 y luego se detiene para esa conexión.
• La secuencia permanece abierta más de 10 segundos y luego se cierra, como suele ocurrir con las secuencias hacia hosts serverless: después de cinco reaperturas en una hora, Claude Code espera aproximadamente seis horas antes de la siguiente.

Hasta que la secuencia se reabre, conservas las herramientas, prompts y recursos del servidor obtenidos por última vez. Para recoger sus cambios antes, reconecta 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 ves depende de cómo estés 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 que necesita autenticación cuando el servidor necesita autorizarse de nuevo. Cuando marca el servidor como fallido, ves una notificación MCP server "<name>" disconnected · open /mcp to reconnect. Puedes reintentar manualmente desde /mcp.
• En ejecuciones de claude -p y sesiones del Agent SDK: Claude Code se reconecta con el mismo cronograma, sin panel /mcp para mostrar los intentos.

Conexiones iniciales fallidas

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 que se agote el 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 no reintenta en estos casos:

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

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 un retroceso corto después de un error transitorio de red o del servidor. No reintenta errores de autenticación, respuestas 4xx, ni solicitudes cuyo tiempo de espera se agota.

Reintentar tú mismo los servidores fallidos

Para reintentar todos los servidores que fallaron o necesitan autenticación, ejecuta /mcp reconnect all. En la terminal interactiva esto requiere Claude Code v2.1.284 o posterior, y las versiones anteriores imprimen MCP server "all" not found allí.

Cómo Claude se entera de que un servidor falló

Que Claude Code le informe a Claude sobre un servidor configurado que no pudo conectarse depende de la búsqueda de herramientas, que está activada 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 la falla de conexión en su respuesta. Claude Code incluye la misma información en los resultados de ToolSearch que no encuentran ninguna herramienta coincidente.
• En cualquier configuración sin búsqueda de herramientas, Claude Code no informa a Claude de las conexiones fallidas de servidores.

Enviar mensajes con canales

Un servidor MCP también puede enviar mensajes directamente a tu sesión para que Claude pueda reaccionar a eventos externos como resultados de CI, alertas de monitoreo, o mensajes de chat. Para habilitar esto, tu servidor declara la capacidad claude/channel y tú lo activas con el flag --channels al inicio. Consulta Channels para usar un canal con soporte oficial, o Channels reference para crear el tuyo propio.

En el tiempo de ejecución v2, si estableces 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 protocolo anterior.

El timeout por servidor es un límite estricto de tiempo real por llamada a herramienta, y las notificaciones de progreso del servidor no lo extienden. Los valores por debajo de 1000 se ignoran y se recurre a MCP_TOOL_TIMEOUT, o a su valor predeterminado de aproximadamente 28 horas cuando esa variable no está establecida. Para un servidor HTTP, SSE, o de 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 en el mayor de tres valores: 60 segundos, el tiempo de espera de herramientas que se aplica al servidor, y MCP_TIMEOUT. El valor predeterminado de 28 horas de un MCP_TOOL_TIMEOUT sin establecer 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 mínimo para el tiempo de espera de inactividad descrito a continuación: Claude Code nunca aborta las llamadas a herramientas de ese servidor por inactividad antes del timeout por servidor. Requiere Claude Code v2.1.203 o posterior.

Una llamada a herramienta a un servidor MCP que no envía respuesta ni notificación de progreso durante la ventana de inactividad se aborta con un error en lugar de esperar el límite de tiempo real. El tiempo de espera de inactividad se aplica a todos los tipos de servidor excepto los servidores IDE y los servidores SDK en proceso. La ventana de inactividad tiene un valor predeterminado de cinco minutos para servidores HTTP, SSE, WebSocket, y de 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.

Establece la variable de entorno CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT en milisegundos para cambiar la ventana de inactividad, o establécela en 0 para deshabilitar 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 la conversación principal que se ejecuta más de dos minutos pasa antes a una tarea en segundo plano. Consulta Automatic backgrounding of long tool calls.

Ejecución automática en segundo plano de llamadas a herramientas largas

Una llamada a herramienta MCP en la conversación principal que aún se está ejecutando después de dos minutos pasa a una tarea en segundo plano en lugar de bloquear la sesión. Claude recibe el ID de la tarea inmediatamente y sigue trabajando, y el resultado llega como una notificación de tarea cuando la llamada termina. La ejecución automática en segundo plano requiere Claude Code v2.1.212 o posterior.

La tarea aparece en /tasks, donde también puedes detenerla, y no sobrevive a la salida de la sesión. La entrada de la tarea muestra el progreso más reciente que el servidor ha informado.

Los límites por llamada aún se aplican mientras la llamada se ejecuta en segundo plano: el límite de tiempo real 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.

Establece la variable de entorno CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS en milisegundos para cambiar el umbral, o establécela en 0 para desactivar la ejecución automática en segundo plano. Establecer CLAUDE_CODE_DISABLE_BACKGROUND_TASKS en 1 también la desactiva, junto con todas las demás funciones de tareas en segundo plano.

Algunas llamadas nunca pasan a segundo plano:

• Llamadas de subagentes; Claude Code solo pasa a segundo plano las llamadas de la 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 única puede terminar antes de que llegue el resultado

Una llamada que espera en un diálogo de elicitación abierto no pasa a segundo plano mientras el diálogo está abierto; el servidor está bloqueado esperando tu entrada, no es lento, por lo que Claude Code pospone el paso hasta que el diálogo se cierre.

Servidores MCP proporcionados por plugins

Los plugins pueden incluir servidores MCP que proporcionan herramientas e integraciones cuando habilitas 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 habilitas un plugin, Claude Code inicia sus servidores MCP automáticamente
• Claude Code ofrece las herramientas MCP de plugins junto con las herramientas MCP configuradas manualmente
• Agregas y eliminas servidores de plugins instalando o desinstalando el plugin, no con comandos /mcp. Aún puedes desactivar un servidor de plugin instalado en /mcp, lo que hace que Claude Code deje de conectarse 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 MCP de plugins:

• Ciclo de vida automático: los servidores se conectan y desconectan en estos momentos:
  • Al inicio de la sesión, Claude Code conecta automáticamente los servidores de los plugins habilitados. En /mcp, un servidor de plugin remoto (HTTP o SSE) que hayas 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 habilitas o deshabilitas un plugin durante una sesión, Claude Code conecta o desconecta sus servidores MCP cuando el cambio se aplica. Apply plugin changes without restarting describe cuándo sucede eso. En una sesión sin terminal interactiva, /reload-plugins no conecta ni desconecta servidores MCP de plugins; esos cambios surten efecto en tu próxima sesión
  • Cuando recargas, Claude Code mantiene las conexiones activas de los servidores de plugins cuya configuración no ha cambiado, y hace lo mismo cuando reemplazas la lista de servidores MCP de la sesión desde el Agent SDK sin nombrarlos
  • Cuando mueves la sesión con /cd en v2.1.246 o posterior, Claude Code conecta los servidores de los plugins que la configuración del nuevo directorio habilita y desconecta los servidores de los plugins que ya no están habilitados, por lo que no necesitas ejecutar /reload-plugins después del cambio
  • En sesiones en la nube, una llamada MCP a un servidor de plugin que aún no está conectado, como justo después de que se reactive una sesión inactiva, 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 estable del proyecto. La sustitución se aplica a:
  • servidores stdio: command, args, env
  • servidores http, sse, y ws: url, headers, y headersHelper
• Acceso al 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.

Para un servidor stdio de un plugin, claude mcp get imprime Command: stdio, una línea Args: vacía, y cada variable de entorno como NAME=[REDACTED]. Los valores están ocultos porque pueden contener credenciales.

Nombres de herramientas MCP de plugins:

Las herramientas de un servidor MCP incluido en un plugin contienen 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 incluido en un plugin llamado my-plugin, una herramienta query es invocable como:

mcp__plugin_my-plugin_database-tools__query

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

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

Consulta la referencia de componentes de plugins para obtener detalles sobre cómo incluir servidores MCP en 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

Claude Code coincide duplicados en los tres alcances 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.

Dos ortografías de URL cuentan como el mismo punto final cuando difieren solo en la mayúscula y minúscula de la letra del esquema u host, el puerto predeterminado del esquema, como :443 en https, o una barra diagonal final. Una ruta diferente, cadena de consulta, información de usuario o puerto no predeterminado hace que sean servidores diferentes.

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}"
      }
    }
  }
}

Variables de entorno no establecidas sin un valor predeterminado

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. En la url y headers de un servidor remoto, algunas variables de credenciales se leen como vacías en su lugar, sin advertencia.

Variables de credenciales que se leen como vacías

En la url y headers de un servidor remoto, Claude Code lee las variables de credenciales de su entorno como vacías en lugar de expandirlas. Esto evita que la .mcp.json de un proyecto o un plugin envíe sus credenciales de Claude Code o proveedor de nube a un servidor que nombra. Si escribe Bearer ${ANTHROPIC_AUTH_TOKEN}, el servidor recibe Bearer sin credencial y rechaza la solicitud, generalmente con un 401. Claude Code informa eso como una conexión fallida.

Los nombres cubiertos son:

• Las propias credenciales de Claude Code, como ANTHROPIC_API_KEY y ANTHROPIC_AUTH_TOKEN
• Las credenciales de su proveedor de nube, como AWS_BEARER_TOKEN_BEDROCK
• Otras credenciales que su entorno lleva, como HTTPS_PROXY y NPM_TOKEN

Un nombre cubierto se lee como vacío independientemente de si ha establecido la variable, y un fallback :-default en él se ignora. Una URL base del proveedor como ANTHROPIC_BASE_URL aún se expande, por lo que "url": "${ANTHROPIC_BASE_URL}/mcp" funciona, a menos que el valor de la URL en sí incruste una credencial como un nombre de usuario y contraseña.

Un nombre fuera de este conjunto, como API_KEY, se expande tal como está escrito. Para dar al servidor una de las credenciales cubiertas, cópiela en una variable con un nombre de su propia elección y haga referencia a ese nombre en su lugar.

Cuando la url o headers de un servidor remoto hace referencia a una variable cubierta que ha establecido, Claude Code la nombra en una línea de registro de depuración. Para leer la línea, ejecute claude --debug-file /tmp/claude-debug.log y busque en ese archivo never expanded toward a remote server.

Cómo aparecen las referencias en `/mcp` y salida de CLI

Para un servidor en el alcance local, de proyecto o de usuario, las siguientes superficies muestran una referencia ${VAR} por nombre en lugar de como su valor resuelto:

• La URL o línea de comandos en la vista de detalle /mcp de un servidor
• Salida de claude mcp list y claude mcp get

La vista de detalle /mcp muestra referencias de esta manera en Claude Code v2.1.268 o posterior.

Para un servidor que su organización proporciona a través de la configuración managedMcpServers, estas superficies muestran solo el host de la URL.

Para verificar qué muestran claude mcp list, claude mcp get e /mcp cuando una conexión falla, vea Detalle de estado del servidor.

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 necesita 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 los 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 volver a autorizar 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 al conectar no marca el servidor, porque la credencial a corregir es la que configuró. Claude Code informa que la conexión falló en su lugar. Si establece ese encabezado desde una referencia ${VAR}, verifique si esa variable es una que Claude Code lee como vacía.
• 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 inició 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 necesita autenticación para el resto de la sesión aunque su token de actualización aún fuera 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, para que no tenga que abrir /mcp para descubrir qué servidores necesitan inicio de sesión. El aviso requiere Claude Code v2.1.193 o posterior. Solo cuenta los 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.

El aviso anuncia cada servidor una vez y lo excluye del recuento en lanzamientos posteriores hasta que ese servidor se haya conectado y necesite iniciar sesión nuevamente. /mcp aún enumera todos los servidores que necesitan iniciar sesión.

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 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 informa que la conexión falló 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

El comando claude mcp login <name> ejecuta el flujo de OAuth de un servidor configurado directamente desde su shell, para que no necesite 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>.

claude mcp login 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 redirección completa de la barra de direcciones de su navegador nuevamente en el aviso. El comando necesita una terminal interactiva para el paso de pegado, así que conéctese con ssh -t. Pase --no-browser para forzar el aviso de URL incluso cuando se detecta un navegador local.

claude mcp login sentry --no-browser

Use un puerto de devolución de llamada de OAuth fijo

Algunos servidores MCP requieren un URI de redirección específico registrado con anticipación. 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 para que coincida con un URI de redirección preregistrado del formulario http://localhost:PORT/callback. Si el inicio de sesión en Claude Code v2.1.229 falla con una falta de coincidencia de URI de redirección, consulte la nota de versión en Use pre-configured OAuth credentials.

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

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Use credenciales de OAuth preconfiguradas

Algunos servidores MCP no admiten la configuración automática de OAuth a través del 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 del 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

Anule el descubrimiento de metadatos de OAuth

Apunte Claude Code a una URL de metadatos de servidor de autorización de 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 Recurso Protegido de RFC 9728 en /.well-known/oauth-protected-resource, luego recurre a los metadatos del servidor de autorización de 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://. El scopes_supported de la URL de metadatos anula los alcances que el servidor ascendente anuncia.

Restrinja los alcances de OAuth

Establezca oauth.scopes para fijar los alcances que Claude Code solicita durante el flujo de autorización. Esta es la forma admitida 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 prioridad sobre authServerMetadataUrl y 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 recurso protegido, 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 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 agrega a los alcances fijados para que el token de acceso pueda actualizarse sin un nuevo inicio de sesión del navegador.

Si el servidor luego devuelve un 403 insufficient_scope para una llamada de herramienta, la llamada falla con un mensaje needs additional permissions que nombra el alcance que el servidor solicita. El servidor se muestra como que necesita autenticación en /mcp.

Si ese alcance no está en su oauth.scopes fijado, agréguelo, luego ejecute /mcp y autentique el servidor nuevamente. Claude Code solicita los alcances fijados en lugar del alcance que el servidor nombró, por lo que si se autentica nuevamente sin agregarlo, el token que obtiene aún carece de él.

Use encabezados dinámicos para autenticación personalizada

Si su servidor MCP usa un esquema de autenticación distinto de 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 helper nuevamente en cada conexión, al inicio de 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 token.

Si una llamada de herramienta devuelve 401 Unauthorized o 403 Forbidden, Claude Code ejecuta automáticamente el helper nuevamente 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 helper 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 helper al conectar, Claude Code informa que la conexión falló en lugar de marcar el servidor como que necesita autenticación. Corrija la credencial que devuelve su helper, luego reconéctese desde /mcp para ejecutar el helper nuevamente.

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

Úselos para escribir un único script helper que sirva a 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 informa que el servidor está mal configurado con un error y no sustituye el valor. Coloque ${user_config.KEY} en el campo headers del servidor en su lugar, que no se analiza mediante shell, o haga que el script helper 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 helper

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 helpers de servidores de alcance de usuario, administrados y de conector de claude.ai, y de archivos de agente de fuera de su proyecto, desde el directorio en el que lo inició.

Qué variables puede leer un helper

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:

• Eliminado: un servidor en un proyecto .mcp.json 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 eliminado: 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 todas las variables de su entorno cuyo nombre parece 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 helper, haga que el script lea su credencial de un archivo o un almacén de credenciales. Si la url del servidor lleva el valor en vivo de una de estas variables, como MY_REGISTRY_TOKEN, el valor CLAUDE_CODE_MCP_SERVER_URL que recibe el helper también tiene esa parte reemplazada con REDACTED.

Confíe 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 proyecto .mcp.json o en alcance local, ejecuta el helper solo después de que acepte el diálogo de confianza para el directorio del proyecto en el que se declara el servidor. Antes de v2.1.238, una sesión claude -p o SDK ejecutaba estos helpers sin verificar la 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 su headers estático. 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 Project allow rules and workspace trust 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 helper 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

Anthropic también proporciona algunos conectores por sí mismo, sin que usted o un administrador los añadan. En cuentas donde Claude Docs está disponible, /mcp enumera claude.ai Claude Docs sin configuración, y Claude lo usa cuando le pide un documento destinado a otras personas. Para desactivarlo, añada una entrada serverName de "claude.ai Claude Docs" a deniedMcpServers o use el botón de alternancia /mcp, ambos descritos en Desactivar conectores de claude.ai.

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 un problema de 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 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. 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 de Claude. En sesiones donde Claude Code obtiene conectores por sí mismo, la lista de herramientas /mcp aún muestra la herramienta, marcada como disabled by your organization.

La aplicación de escritorio y el chat de claude.ai aplican la misma configuración blocked, por lo que Claude tampoco puede usar una herramienta bloqueada 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.

Imágenes en resultados de herramientas

Cuando una herramienta de MCP devuelve una imagen PNG, JPEG, GIF o WebP, Claude ve la imagen en línea en la conversación. La copia en línea puede estar reducida o comprimida para ajustarse a los límites de tamaño de imagen del modelo. Claude Code también guarda los bytes originales en un archivo en el directorio tool-results de la sesión bajo ~/.claude/projects/ y le proporciona a Claude la ruta. Claude puede entonces recortar, convertir o reutilizar el archivo de resolución completa con herramientas como Bash.

Si desactiva la persistencia de sesión con --no-session-persistence o CLAUDE_CODE_SKIP_PROMPT_HISTORY, Claude Code no escribe ningún archivo de imagen y Claude recibe solo la copia en línea.

Guardar resultados de imágenes de MCP en un archivo requiere Claude Code v2.1.283 o posterior.

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.

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

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 pregunta si desea abrir un enlace en su navegador y lo abre cuando usted acepta. Los servidores utilizan este modo para un flujo que se completa fuera de la terminal, como el inicio de sesión.

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.

En conexiones que utilizan revisión de protocolo 2026-07-28, Claude Code declara elicitation: {form: {}, url: {}} en sus capacidades de cliente, por lo que un servidor allí puede solicitar cualquiera de los modos a través de la solicitud de elicitación estándar del protocolo.

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

Los recursos de la interfaz de usuario de MCP Apps son entradas con un URI ui:// o el tipo de medio text/html;profile=mcp-app: páginas para que una aplicación host renderice en lugar de contenido para que Claude lea. No aparecen en las sugerencias de @ ni en los resultados de la herramienta de lista de recursos, y un servidor que ofrece solo recursos de interfaz de usuario muestra una lista de recursos vacía. Leer un recurso de interfaz de usuario por su URI sigue funcionando.

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 cada descripción de herramienta e instrucciones de cada servidor en 2.048 caracteres de forma predeterminada. Manténgalas concisas y coloque los detalles críticos cerca del inicio.

Para cambiar el límite para cada servidor MCP en su sesión, establezca CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH en un número de caracteres. Esta variable requiere Claude Code v2.1.280 o posterior.

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.

Los prompts de un servidor llamado anthropic-skills no aparecen, porque Claude Code reserva ese nombre para skills sincronizadas desde claude.ai. Las herramientas del servidor siguen funcionando. Renombre el servidor en su configuración de MCP para enumerar sus prompts.

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.