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.

[!WARNING]

Verifique que confía en cada servidor antes de conectarlo. Los servidores que obtienen contenido externo pueden exponerlo al riesgo de inyección de indicaciones.

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.

1. Instalar el plugin

En la extensión de VS Code o en la aplicación de escritorio, sigue Instalar un plugin en lugar de este paso. En una terminal, inicia Claude Code ejecutando claude y luego ingresa esto en su prompt:

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

Si la instalación falla, haga coincidir el mensaje que Claude Code reporta:

• Marketplace "claude-plugins-official" not found: agrega el marketplace con /plugin marketplace add anthropics/claude-plugins-official y luego reintenta la instalación.
• Plugin "<name>" not found in marketplace "claude-plugins-official": es posible que tu copia local del catálogo del marketplace esté desactualizada. Actualízala con /plugin marketplace update claude-plugins-official y luego reintenta la instalación. Si el reintento muestra el mismo mensaje, consulta Plugin no encontrado en el marketplace.

Si el resumen de instalación reporta Run /reload-plugins to apply., Claude Code ejecuta esa recarga por ti. Si la recarga advierte que tu próximo mensaje volvería a leer la conversación, ejecuta /reload-plugins --force.

2. Ejecutar el skill de creación

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

Claude le pregunta sobre su caso de uso y crea un servidor HTTP remoto o un servidor stdio local.

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.

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.

[!NOTE]

En ejecuciones con --output-format stream-json, Claude Code también informa de una entrada omitida de --mcp-config en el campo mcp_server_errors del evento system/init, para que los scripts puedan detectar que el servidor nunca se cargó.

Opción 2: Agregar un servidor SSE remoto

[!WARNING]

El transporte SSE (Server-Sent Events) está obsoleto. Usa servidores HTTP en su lugar, cuando estén disponibles.

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.

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

[!NOTE]

Para servidores stdio, el -- (doble guion) separa las opciones propias de Claude, como --transport, --env, y --scope, del comando y los argumentos que ejecutan el servidor. Todo lo que viene después de -- se pasa al servidor sin cambios.

Por ejemplo:

• claude mcp add --transport stdio myserver -- npx server → ejecuta npx server
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 → ejecuta python server.py --port 8080 con KEY=value en el entorno

Sin --, Claude Code intentaría analizar los flags del servidor, como --port arriba, como sus propias opciones.

--env acepta múltiples pares KEY=value. Si el nombre del servidor viene directamente después de --env, la CLI lee el nombre como otro par y lo rechaza, así que coloca al menos otra opción, como --transport stdio, entre --env y el nombre del servidor.

Cómo Claude Code detiene un servidor stdio

Cuando Claude Code desconecta un servidor stdio, por ejemplo cuando termina tu sesión, envía una señal al proceso del servidor y espera brevemente a que termine antes de forzar su detención. Si tu servidor guarda estado o elimina archivos de bloqueo al apagarse, maneja la señal correspondiente a tu plataforma y termina dentro de ese tiempo:

• En macOS y Linux: Claude Code envía SIGINT, luego SIGTERM si el proceso aún se está ejecutando 100 milisegundos después, y luego SIGKILL tras otros 400 milisegundos.
• En Windows: Claude Code cierra el stdin del servidor y luego finaliza el árbol de procesos del servidor si el proceso aún se está ejecutando 300 milisegundos después.

Antes de v2.1.296, Claude Code en Windows finalizaba el árbol de procesos del servidor de inmediato, sin cerrar primero stdin ni esperar.

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.

Agregar un servidor 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.

Agregar un servidor 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.

Agregar un servidor 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 borra los tokens OAuth y el registro de cliente que almacenó para ese servidor. Claude Code no revoca los tokens en el servidor de autorización que los emitió. Para revocar los tokens cuando el servidor de autorización admite la revocación, ejecuta claude mcp logout <name> en tu shell antes de claude mcp remove <name>.

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.
• ✘ Blocked by enterprise managed policy: un servidor que rechaza una de las políticas de tu organización. Claude Code lo muestra tanto en claude mcp list como en claude mcp get <name>. Un servidor bloqueado por una lista de permitidos, una lista de denegados u otra restricción en la configuración MCP administrada se oculta en ambos comandos en lugar de mostrarse con este estado. Pregunta a tu administrador qué política bloquea el servidor.

Aprobaciones de servidores de proyecto y confianza del espacio de trabajo

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

Errores de conexión y servidores sin configurar

Cuando el estado de un servidor es ✘ Failed to connect, claude mcp list añade el detalle del error a esa línea de estado, y claude mcp get <name> lo muestra en una línea Issue:. El detalle es el estado HTTP o el código de error, más cualquier texto de error que haya devuelto el servidor. 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 que parece una credencial y nunca incluye la URL expandida del servidor, que puede contener secretos. Claude Code no añade ningún detalle a un estado ✘ Connection error, porque el texto de la excepción que imprimiría allí puede incluir esa URL.

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.

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 ENABLE_TOOL_SEARCH=false y un modelo anterior a Claude Opus 4.5, Claude Sonnet 4.5 y Claude Haiku 4.5 en Agent Platform de Google Cloud. Para un gateway ANTHROPIC_BASE_URL, consulta Búsqueda de herramientas a través de un gateway de LLM.
• 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, stdio y de conectores de claude.ai si admiten la revisión más nueva, y la utiliza con los que la admiten. Esto incluye los conectores de las sesiones en la nube y de Remote Control. Claude Code 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.

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. Para un servidor stdio, consulta Servidores stdio que terminan o no logran iniciarse.

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

Claude Code primero intenta reconectar un servidor remoto caído hasta cinco veces con retroceso exponencial, comenzando con un retraso de un segundo y duplicándolo cada vez:

• 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 hace los mismos cinco intentos, sin panel /mcp para mostrarlos. Si los cinco fallan, la ejecución continúa sin las herramientas del servidor:
  • Después de un error transitorio, como una respuesta 5xx o que se agote el tiempo de espera: Claude Code sigue reintentando un servidor HTTP o SSE en segundo plano. Los reintentos duran hasta aproximadamente media hora, y las herramientas del servidor vuelven a estar disponibles cuando uno se conecta. Hasta entonces, una sesión del Agent SDK informa el estado failed, y tu código puede reconectar el servidor. Para reconectarlo en claude -p, vuelve a iniciar la ejecución.
  • Cuando el servidor necesita que vuelvas a iniciar sesión: Claude Code deja de reintentar, y una sesión del Agent SDK informa el estado del servidor como needs-auth. Inicia sesión con claude mcp login <name> en tu shell. Luego vuelve a iniciar la ejecución o, en una sesión del Agent SDK, reconecta el servidor en su lugar.

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.

Esos reintentos no se aplican en estos casos:

• La primera conexión de un servidor stdio. Para intentarla de nuevo, consulta Servidores stdio que terminan o no logran iniciarse
• La primera conexión de un servidor WebSocket. Para intentarlo de nuevo en una sesión interactiva de terminal, selecciona Reconnect en el menú del servidor en /mcp
• 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

Servidores stdio que terminan o no logran iniciarse

Para volver a iniciar un servidor stdio, lee la columna que corresponde a lo que le pasó. Encuentra tu fila según cómo ejecutas Claude Code: una sesión interactiva, una ejecución de claude -p, o una sesión del Agent SDK.

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 el prompt de Claude Code en una sesión interactiva de terminal. Esto requiere Claude Code v2.1.284 o posterior. Las versiones anteriores imprimen MCP server "all" not found.

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, un servidor de canal que 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. Un servidor de canal que no admite esa revisión se conecta con el handshake anterior y se registra como antes.

Claude Code pregunta a los servidores stdio por esa revisión de forma predeterminada. Para mantener un servidor de canal stdio en el handshake anterior, establece MCP_PROTOCOL_NEGOTIATION en legacy, lo que mantiene todos los servidores en él.

[!TIP]

Consejos:

• Usa el flag -s o --scope para especificar dónde se almacena la configuración:
  • local (predeterminado): disponible solo para ti en el proyecto actual
  • project: compartido con todos en el proyecto a través del archivo .mcp.json
  • user: disponible para ti en todos los proyectos
• Establece variables de entorno con los flags -e o --env (por ejemplo, -e KEY=value)
• Los flags --transport y --header también aceptan las formas cortas -t y -H
• Configura el tiempo de espera de inicio del servidor MCP usando la variable de entorno MCP_TIMEOUT (por ejemplo, MCP_TIMEOUT=10000 claude establece un tiempo de espera de 10 segundos)
• Establece un tiempo de espera de ejecución de herramientas por servidor agregando un campo timeout en milisegundos a la entrada .mcp.json de ese servidor, por ejemplo "timeout": 600000 para diez minutos. Esto sobrescribe la variable de entorno MCP_TOOL_TIMEOUT solo para ese servidor
• Claude Code muestra una advertencia cuando la salida de herramientas MCP excede 10,000 tokens y limita la salida a 25,000 tokens de forma predeterminada. Para cambiar el límite de tokens, establece la variable de entorno MAX_MCP_OUTPUT_TOKENS, por ejemplo MAX_MCP_OUTPUT_TOKENS=50000. El umbral de advertencia es fijo. A menos que el servidor aumente el límite propio de una herramienta, los resultados de texto exitosos de más de 50,000 caracteres se guardan en un archivo independientemente de esta variable. Consulta MCP output limits and warnings
• Usa /mcp para autenticarte con servidores remotos que requieren autenticación OAuth 2.0

Límites de tiempo en las llamadas a herramientas MCP

Para limitar cuánto tiempo puede durar una llamada a herramienta MCP:

• Por servidor: agrega un campo timeout en milisegundos a la entrada de configuración de ese servidor
• Para todos los servidores: establece MCP_TOOL_TIMEOUT

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.

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.

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

Si la vista de detalle de una llamada en segundo plano en /tasks muestra runs on the server; survives exiting this session, consulta Tareas MCP que se ejecutan en el servidor.

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 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. Si detienes la tarea, Claude Code cancela la llamada y le dice a Claude que no llegará ningún resultado. Detenerla no garantiza que el servidor se detenga: puede que ya haya hecho parte del trabajo, o que aún lo termine.

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.

Para cambiar o desactivar el paso automático a segundo plano:

• Establece la variable de entorno CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS en milisegundos para cambiar el umbral, o establécela en 0 para desactivar el paso automático a segundo plano. Con 0, Claude también espera las tareas MCP en una sesión interactiva
• Establece CLAUDE_CODE_DISABLE_BACKGROUND_TASKS en 1 para desactivar el paso automático a segundo plano y los comandos 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.

Tareas MCP que se ejecutan en el servidor

Una tarea MCP es un trabajo largo, como una exportación de informe o una compilación, que un servidor MCP ejecuta por sí mismo usando la extensión de tareas de MCP. La llamada a herramienta de Claude regresa en cuanto el servidor acepta el trabajo, así que Claude sigue trabajando a menos que hagas que Claude espere. Cuando el trabajo termina, la transcripción lo indica y Claude recibe el resultado. Pídeselo a Claude.

Mientras tanto, el pie muestra un recuento como 1 MCP task, y Claude Code sigue la tarea consultando su estado con el servidor. Una tarea en un servidor remoto sigue ejecutándose después de que sales. Para volver a seguirla, reanuda la misma sesión.

[!NOTE]

Las tareas MCP están en beta pública en la CLI de Claude Code y requieren Claude Code v2.1.304 o posterior. Qué necesita una llamada para convertirse en una tarea MCP enumera las sesiones y los servidores que las obtienen.

Detener una tarea MCP u obtener su resultado

Para detener una tarea en ejecución, selecciónala en /tasks y presiona x, o pídeselo a Claude. Claude Code deja de seguir la tarea y le pide al servidor que la cancele, aunque el servidor puede terminarla de todos modos. Vuelve a conectar primero un servidor desconectado desde /mcp, o no se envía ninguna solicitud de cancelación y Claude Code olvida la tarea y no puede volver a seguirla. Presionar Esc no detiene una tarea en segundo plano.

Cuando la tarea termina, aparece en la transcripción una línea como esta:

MCP task <server task id> (<server>/<tool>) completed.

El resultado va a Claude, no a la transcripción, así que pídeselo a Claude. Si Claude está inactivo cuando llega el resultado, Claude se pone a trabajar con él sin que se lo pidas.

Responder a una pregunta de una tarea MCP

Una tarea en ejecución puede abrir un diálogo de elicitación para pedirte información. Mientras /tasks está abierto, el diálogo permanece oculto, así que cierra /tasks para responder. Rechazar o presionar Esc es una respuesta para el servidor, que entonces decide si la tarea continúa.

En una sesión no interactiva, Claude Code le pide al servidor que cancele una tarea que solicita información, sin ejecutar tus hooks Elicitation ni llamar al callback onElicitation del Agent SDK.

Salir, limpiar o reanudar mientras se ejecuta una tarea MCP

Una tarea en un servidor remoto sigue ejecutándose después de que sales. El proceso de un servidor stdio se detiene cuando Claude Code sale, aunque sus tareas muestren runs on the server; survives exiting this session en /tasks. A menos que la documentación de ese servidor indique que el trabajo sobrevive al proceso, deja que esas tareas terminen o detenlas primero en /tasks.

Qué necesita una llamada para convertirse en una tarea MCP

Una llamada a herramienta se convierte en una tarea MCP solo cuando se cumplen todas estas condiciones:

• El servidor admite tareas
• El servidor es un servidor HTTP, stdio o de conector de claude.ai conectado con la revisión 2026-07-28 del protocolo. Establecer MCP_SDK_GENERATION=v1 o MCP_PROTOCOL_NEGOTIATION=legacy lo descarta
• La sesión obtiene feature flags, así que no en un proveedor externo como Amazon Bedrock, ni con la telemetría o la obtención de flags desactivadas
• Anthropic ha activado las tareas MCP para tu tipo de sesión. En v2.1.304 o posterior eso abarca las sesiones de la CLI en terminal, las sesiones del Agent SDK y las ejecuciones de GitHub Actions. Otras superficies, como la extensión de VS Code y la aplicación de escritorio, no tienen tareas MCP
• La llamada proviene de la conversación principal, no de un subagente
• O bien la sesión es interactiva, o bien una sesión del Agent SDK o una ejecución de claude -p que lee --input-format stream-json tiene:
  • CLAUDE_AUTO_BACKGROUND_TASKS en 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND distinto de 1
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS distinto de 0

Cualquier otra llamada es una llamada a herramienta normal, y Paso automático a segundo plano de las llamadas a herramientas largas indica cuáles de ellas pasan a segundo plano.

Mantén abierta la entrada de una sesión del Agent SDK o de stream-json, porque la ejecución no espera a las tareas MCP después de que se cierra la entrada. Una ejecución única claude -p "<prompt>" no obtiene tareas MCP.

Mensajes de estado de una tarea MCP

Estos mensajes, en la entrada de una tarea en /tasks o en su línea final de la transcripción, significan que Claude Code no puede comunicarse con el servidor o con la tarea. Mientras se muestra uno en /tasks, el trabajo puede seguir en ejecución: Claude Code no lo toca y sigue comprobando. Los mensajes de 300s y de configuración permanecen en la entrada incluso después de que se restablece el contacto.

Límites de tiempo en las tareas MCP

De forma predeterminada, una tarea en segundo plano no tiene límite de tiempo de Claude Code. Los límites de tiempo de las llamadas a herramientas, incluidos el límite de tiempo real y el tiempo de espera por inactividad, se aplican hasta que el servidor responde a la llamada con la tarea. Si haces que Claude espere, se aplican durante toda la tarea. Las comprobaciones de estado respondidas cuentan como actividad para el tiempo de espera por inactividad.

Hacer que Claude espere el resultado de una tarea MCP

Para que Claude espere el resultado de una tarea en una sesión interactiva, establece una de dos variables de entorno, por ejemplo en el bloque env de settings.json:

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS establecida en 0: Claude espera cada llamada a herramienta MCP hasta que la llamada termina
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND establecida en 1: Claude espera el resultado de una tarea. Mientras el paso automático a segundo plano está activado, mueve la llamada después de dos minutos de forma predeterminada, así que las tareas cortas terminan en su lugar y las largas no te bloquean. La llamada movida es una llamada normal en segundo plano y no una tarea MCP. No sobrevive a la salida de la sesión

Mientras Claude espera, presionar Esc o alcanzar el límite de tiempo real o el tiempo de espera por inactividad termina la llamada, y Claude Code le pide al servidor que cancele la tarea.

Si estableces CLAUDE_CODE_DISABLE_BACKGROUND_TASKS en 1 o inicias en modo bare, eso por sí solo no hace que Claude espere las tareas MCP. Este ejemplo establece CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS en 0, así que Claude espera cada llamada a herramienta MCP:

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

Tareas MCP para autores de servidores

Si creas un servidor MCP, puedes responder a un tools/call de larga duración con una tarea. La extensión de tareas de MCP define los mensajes que envías. En una conexión con la revisión 2026-07-28 del protocolo, cada solicitud lleva las capacidades de cliente de Claude Code en params._meta["io.modelcontextprotocol/clientCapabilities"], con "io.modelcontextprotocol/tasks": {} bajo extensions. Una solicitud tools/call que no puede convertirse en una tarea omite esa extensión.

Responder a la llamada con una tarea

Responde con una tarea solo cuando la solicitud lleve la extensión, o Claude recibe el error de herramienta Unsupported result type 'task' for tools/call. Claude recibe el mismo error cuando falta taskId, status, createdAt, lastUpdatedAt o ttlMs. El objeto de la tarea es el result de JSON-RPC de tu respuesta a tools/call, no necesita un arreglo content y aquí incluye los campos opcionales statusMessage y pollIntervalMs:

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

En un servidor HTTP o de conector de claude.ai, la respuesta con la tarea tiene que empezar dentro del temporizador por solicitud, así que acepta el trabajo y responde primero, y luego haz el trabajo.

Informar estado, resultados y preguntas

Justo después de la respuesta con la tarea, Claude Code envía tasks/get con { "taskId": ... }, y luego lo repite una vez por intervalo de sondeo. La extensión de tareas exige que tu respuesta lleve "resultType": "complete" junto con taskId, status, createdAt, lastUpdatedAt y ttlMs. ttlMs puede ser null, y statusMessage y pollIntervalMs son opcionales. Este ejemplo informa que la compilación terminó:

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

Servidores MCP proporcionados por plugins

Los plugins pueden incluir servidores MCP que proporcionan herramientas e integraciones cuando habilitas el plugin.

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. Cuando la conexión de un servidor de plugin stdio falló hace menos de 15 minutos, Claude Code omite la conexión
  • 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.

claude mcp get oculta los valores configurados para el servidor stdio o WebSocket de un plugin, porque pueden contener credenciales:

• Servidor stdio: imprime Command: stdio, una línea Args: vacía, y cada variable de entorno como NAME=[REDACTED]
• Servidor WebSocket: imprime URL: ws y cada encabezado como <name>: [REDACTED], y claude mcp list muestra ws en lugar de la URL

Para ver lo que configuró el plugin, busca el plugin en el disco y lee su .mcp.json o plugin.json.

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.

[!NOTE]

El término "alcance local" para servidores MCP difiere de la configuración local general. Los servidores MCP con alcance local se almacenan en ~/.claude.json (su directorio de inicio), mientras que la configuración local general usa .claude/settings.local.json (en el directorio del proyecto). Vea Configuración para detalles sobre ubicaciones de archivos de configuración.

# 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. Incluya .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 fuera de los hilos de un proyecto, Claude Code no puede mostrar esa solicitud: carga servidores con alcance de proyecto sin preguntar. Claude Code también omite la solicitud en una sesión que inicias en modo bypassPermissions con skipDangerousModePermissionPrompt establecido en tu 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.

Puedes hacer referencia a una variable de entorno en el valor command, args, env, url o headers de un servidor, de cualquiera de estas dos formas:

• ${VAR}: se expande al valor de la variable de entorno VAR
• ${VAR:-default}: se expande al valor de VAR si VAR está establecida, o a default si no lo está

Ejemplo con expansión de variables

En esta entrada de servidor, la URL es el valor de API_BASE_URL seguido de /mcp, con https://api.example.com como valor predeterminado, y la clave de API proviene de API_KEY:

{
  "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 establecidas como cadena vacía

Si estableces una variable como cadena vacía, cuenta como establecida, por lo que una referencia ${VAR:-default} se expande a la cadena vacía en lugar de a default. Con el servidor de ejemplo, si estableces API_BASE_URL como cadena vacía, su url se convierte en /mcp y claude mcp list informa 'url' is not a valid URL. Para usar el valor predeterminado, elimina la variable en lugar de establecerla como cadena vacía.

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"

Reemplaza YOUR_GITHUB_PAT con tu token de acceso personal. El comando claude mcp add guarda la configuración sin validar credenciales, por lo que aquí se acepta un valor de marcador de posición, pero el servidor no logra conectarse más tarde. Para verificar la conexión, ejecuta /mcp y comprueba que la fila del servidor muestre una marca de verificación. Un servidor con credenciales incorrectas muestra en su lugar una ✘, y su detalle de fallo incluye el estado HTTP que devolvió el servidor, como un 401.

Luego trabaje con GitHub:

Revisa el PR #456 y sugiere mejoras

Crea un nuevo issue 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, ejecuta /mcp y comprueba que la fila de db muestre una marca de verificación.

Luego consulte su base de datos de forma natural:

¿Cuál es nuestro ingreso total este mes?

Muéstrame el esquema de la tabla de pedidos

Encuentra los 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 has iniciado sesión, cualquiera de los códigos de estado lo marca en /mcp para que puedas completar el flujo de OAuth.
• Para un conector de claude.ai, un 401 causado por claude.ai rechazando tu token de sesión no marca el conector, porque volver a autorizar el conector no puede solucionar tu inicio de sesión. Claude Code muestra el estado de token de sesión rechazado en su lugar.
• Para un servidor cuyo encabezado Authorization configuraste, 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 configuraste. Claude Code informa que la conexión falló en su lugar. Si estableces ese encabezado desde una referencia ${VAR}, verifica 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 otorgaste en claude.ai. Cuando un conector allí necesita autorización nuevamente, reconéctalo en claude.ai/customize/connectors en lugar de desde la sesión.

Cuando un servidor OAuth en el que ya iniciaste sesión rechaza tu token almacenado con 401 Unauthorized, Claude Code actualiza el token, se reconecta e intenta la solicitud una vez más. Solo marca el servidor en /mcp si ese reintento también falla. En una ejecución de claude -p o del Agent SDK en macOS, una solicitud que Claude Code envió mientras no podía leer tu token almacenado falla en su lugar con un error de credenciales almacenadas.

Cuando el servidor rechaza el token de actualización almacenado, Claude Code muestra inmediatamente un aviso que apunta a /mcp. Abre /mcp y selecciona Re-authenticate en el servidor para iniciar sesión nuevamente antes de que la siguiente llamada a 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 tengas que abrir /mcp para descubrir qué servidores necesitan inicio de sesión. El aviso solo cuenta los servidores en los que puedes 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 puedes 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.

Una ejecución de claude -p o del Agent SDK no tiene panel /mcp, por lo que Claude Code no puede ejecutar el flujo de OAuth allí. Para usar un servidor que necesita autenticación, completa primero el inicio de sesión desde una sesión interactiva: ejecuta /mcp en la sesión, o claude mcp login <name> en tu shell. Cuando un servidor configurado necesita autenticación durante una ejecución de claude -p o del Agent SDK con búsqueda de herramientas habilitada, Claude Code le dice a Claude que las herramientas del servidor no están disponibles hasta que lo autorices.

Si configuraste 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. Verifica que el token sea válido para el endpoint de MCP, o elimina el encabezado para usar el flujo de OAuth.

1. Agrega el servidor que requiere autenticación

Si ya agregaste el servidor sentry en el inicio rápido de MCP, omite este paso: ejecutar claude mcp add nuevamente con el mismo nombre de servidor en el mismo alcance falla con MCP server sentry already exists in local config. De lo contrario, ejecuta:

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

2. Usa el comando /mcp dentro de Claude Code

En Claude Code, usa el comando:

/mcp

Luego sigue los pasos en tu navegador para iniciar sesión.

[!TIP]

Consejos:

• Los tokens de autenticación se almacenan de forma segura y se actualizan automáticamente
• Usa "Clear authentication" en el menú /mcp para revocar el acceso
• Si tu navegador no se abre automáticamente, copia la URL proporcionada y ábrela manualmente
• Si la redirección del navegador falla con un error de conexión después de autenticarte, pega la URL de devolución de llamada completa de la barra de direcciones de tu navegador en la solicitud de URL que aparece en Claude Code
• La autenticación OAuth funciona con servidores HTTP

Autenticarse desde la línea de comandos

El comando claude mcp login <name> ejecuta el flujo de OAuth de un servidor configurado directamente desde tu shell, para que no necesites abrir el panel /mcp dentro de una sesión. Para un conector de claude.ai, sigue Autorizar un conector de nuevo desde tu shell.

claude mcp login sentry

Para borrar las credenciales almacenadas más tarde, ejecuta 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. Abre la URL en tu máquina local y luego pega la URL de redirección completa de la barra de direcciones de tu navegador en la solicitud. El comando necesita una terminal interactiva para el paso de pegado, así que conéctate con ssh -t. Pasa --no-browser para forzar la solicitud de URL incluso cuando se detecta un navegador local.

claude mcp login sentry --no-browser

Usa 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. Usa --callback-port para fijar el puerto de modo que coincida con un URI de redirección preregistrado de la forma 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, consulta la nota de versión en Usa credenciales de OAuth preconfiguradas.

Puedes 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

Usa 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 ves 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, registra primero una aplicación OAuth a través del portal de desarrolladores del servidor y luego proporciona las credenciales al agregar el servidor.

1. Registra una aplicación OAuth con el servidor

Crea una aplicación a través del portal de desarrolladores del servidor y anota tu ID de cliente y secreto de cliente.

Si el formulario de registro solicita un URI de redirección, elige cualquier puerto disponible e ingresa http://localhost:PORT/callback con ese puerto. Usarás el mismo puerto en el siguiente paso.

En v2.1.229, Claude Code enviaba http://127.0.0.1:PORT/callback en su lugar, y los servidores que coincidían exactamente con el URI de redirección registrado rechazaban el inicio de sesión con una falta de coincidencia de URI de redirección. Claude Code v2.1.231 restauró la forma localhost. Para recuperarte en v2.1.229, actualiza Claude Code, o agrega temporalmente la forma http://127.0.0.1:PORT/callback a los URI de redirección registrados del servidor.

2. Agrega el servidor con tus credenciales

Las pestañas cubren ambos comandos: claude mcp add toma tu ID de cliente y puerto de devolución de llamada como flags, y claude mcp add-json los toma en un objeto oauth. Si registraste un URI de redirección, establece el puerto de devolución de llamada en el puerto de ese URI.

[tab] claude mcp add

Usa --client-id para pasar el ID de cliente de tu aplicación. El flag --client-secret solicita el secreto con entrada enmascarada:

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

[tab] claude mcp add-json

Incluye el objeto oauth en la configuración JSON y pasa --client-secret como un flag separado:

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

[tab] claude mcp add-json (callback port only)

Para fijar solo el puerto de devolución de llamada y dejar que Claude Code registre el cliente automáticamente, establece callbackPort por sí solo:

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

[tab] CI / env var

Establece el secreto a través de una variable de entorno para omitir la solicitud interactiva:

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

3. Autentícate en Claude Code

Ejecuta /mcp en Claude Code y sigue el flujo de inicio de sesión del navegador.

[!TIP]

Consejos:

• El secreto del cliente se almacena de forma segura en el llavero de tu sistema (macOS) o en un archivo de credenciales, no en tu configuración
• Solo puedes establecer el secreto del cliente cuando agregas el servidor. Cuando te autenticas con claude mcp login o desde /mcp, Claude Code usa el secreto almacenado y no solicita uno ni lee MCP_CLIENT_SECRET
• Para agregar o cambiar el secreto más tarde, elimina el servidor con claude mcp remove <name> y luego agrégalo nuevamente con --client-secret y el mismo --scope
• Si el servidor usa un cliente OAuth público sin secreto, usa solo --client-id sin --client-secret
• Estos flags solo se aplican a transportes HTTP y SSE. No tienen efecto en servidores stdio
• Usa claude mcp get <name> para verificar que las credenciales de OAuth estén configuradas para un servidor

Sobrescribe el descubrimiento de metadatos de OAuth

Apunta Claude Code a una URL de metadatos de servidor de autorización de OAuth específica para omitir la cadena de descubrimiento predeterminada. Establece authServerMetadataUrl cuando los endpoints estándar del servidor MCP generen errores, o cuando quieras 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 y luego recurre a los metadatos del servidor de autorización de RFC 8414 en /.well-known/oauth-authorization-server.

Establece authServerMetadataUrl en el objeto oauth de la configuración de tu 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 sobrescribe los alcances que anuncia el servidor ascendente.

Restringe los alcances de OAuth

Establece 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 quieres 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 sobre los alcances que el servidor descubre en /.well-known. Déjalo sin establecer para permitir que el servidor MCP determine el conjunto de alcances solicitados.

Cuando oauth.scopes no está establecido, Claude Code no solicita el catálogo completo de scopes_supported de los metadatos del servidor de autorización descubiertos automáticamente. 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 en el navegador.

Si el servidor luego devuelve un 403 insufficient_scope para una llamada a 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 tu oauth.scopes fijado, agrégalo y luego ejecuta /mcp y autentica el servidor nuevamente. Claude Code solicita los alcances fijados en lugar del alcance que el servidor nombró, por lo que si te autenticas nuevamente sin agregarlo, el token que obtienes aún carece de él.

Usa OAuth con un servidor detrás de un proxy que autentica

Si tu servidor MCP usa OAuth detrás de un proxy o gateway que verifica un encabezado propio, el inicio de sesión falla cuando las solicitudes OAuth llegan sin ese encabezado. Iniciar sesión a través del proxy requiere Claude Code v2.1.299 o posterior, con el encabezado y el inicio de sesión configurados:

• El encabezado del proxy: pásalo con --header, el campo headers o un headersHelper, con el nombre que lee el proxy
• El inicio de sesión OAuth: mantén Authorization fuera de los encabezados configurados y luego inicia sesión con claude mcp login <name> en tu shell. Si configuras un encabezado Authorization, Claude Code lo usa como la credencial del servidor y no recurre a OAuth para ese servidor.

Usa encabezados dinámicos para autenticación personalizada

Cuando una autenticación como Kerberos, tokens de corta duración o un SSO interno necesita encabezados generados en el momento de la conexión, establece el headersHelper del servidor en un comando. Claude Code lo ejecuta al conectar y combina su salida con los encabezados que envía. Este ejemplo usa un script:

{
  "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 según dónde configuraste el servidor, así que proporciona el script como una ruta absoluta o colócalo en PATH
• Los encabezados dinámicos sobrescriben 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 tu script es responsable de cualquier reutilización de token.

Si una llamada a herramienta devuelve 401 Unauthorized o 403 Forbidden, Claude Code ejecuta automáticamente el helper nuevamente bajo la misma regla, se reconecta con los encabezados nuevos 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. Corrige la credencial que devuelve tu helper y luego reconéctate desde /mcp para ejecutar el helper nuevamente.

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

Úsalas 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. Coloca ${user_config.KEY} en el campo headers del servidor en su lugar, que no se analiza mediante shell, o haz 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 a partir 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 indica el directorio contra el cual se resuelve una ruta relativa en tu 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 tu proyecto, desde el directorio en el que lo iniciaste.

Qué variables puede leer un helper

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

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

Aparte de las variables GIT_CONFIG_KEY_<n> de Git, Claude Code elimina todas las variables de tu entorno cuyo nombre parece una credencial, como un nombre que contenga TOKEN, SECRET, PASSWORD, KEY o AUTH en mayúsculas o minúsculas, por lo que tanto ANTHROPIC_API_KEY como 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 tu helper, haz que el script lea su credencial de un archivo o de 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ía en una carpeta antes de que se ejecute su headersHelper

Claude Code ejecuta un headersHelper como un comando de shell arbitrario. Para un servidor en un .mcp.json de proyecto o en alcance local, ejecuta el helper solo después de que aceptes 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 de claude -p o del SDK ejecutaba estos helpers sin verificar la confianza, y una sesión interactiva los ejecutaba una vez que habías confiado en una carpeta principal.

• Confianza que no cuenta: la confianza de una carpeta principal, y la confianza automática que una sesión de claude -p o del SDK obtiene para hooks en archivos de configuración
• Hasta que confíes en la carpeta: Claude Code conecta el servidor solo con sus headers estáticos. En una sesión de claude -p o del SDK también imprime una línea headersHelper not run por servidor en stderr, indicándote cómo otorgar la confianza.
• Confianza sin un diálogo: establece projects["<path>"].hasTrustDialogAccepted en true en ~/.claude.json. <path> es la carpeta en la que, según Reglas de permiso de proyecto y confianza del espacio de trabajo, 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: tu proyecto, para un archivo en su directorio .claude/agents/, o un directorio --add-dir. Hasta que confíes en ese proyecto o directorio en sí, Claude Code no carga el servidor en absoluto, por lo que su helper tampoco se ejecuta nunca.

Inicia sesión en un servidor MCP detrás de un gateway que requiere un encabezado

El inicio de sesión OAuth en un servidor MCP falla cuando un gateway requiere un encabezado, como X-API-Key, y Claude Code no lo envía. Para que Claude Code envíe ese encabezado, agrégalo a la configuración del servidor y usa Claude Code v2.1.299 o posterior:

• Un servidor cuya configuración puedes editar: establécelo en headers o devuélvelo desde un headersHelper
• Un servidor que proporciona MCP administrado o un plugin: pide a tu administrador o al autor del plugin que agregue el encabezado a la entrada del servidor

Luego, Claude Code agrega los encabezados configurados, excepto Authorization, a las solicitudes de inicio de sesión, actualización de token y revocación de token que envía al origen del servidor. El origen del servidor es el esquema, el host y el puerto de su url. Un gateway que requiere el encabezado aún puede detener el inicio de sesión en la página de autorización o en un servidor de autorización en otro origen:

• La página de autorización: inicias sesión en esta página en tu navegador, que no envía los encabezados configurados. Si tu navegador recibe el error del gateway en lugar de la página, pide a quien administra el gateway que deje pasar la página sin el encabezado.
• Un servidor de autorización en otro origen: si un gateway delante de ese servidor también requiere el encabezado, el inicio de sesión falla allí. Pide a quien administra ese gateway que deje pasar las solicitudes OAuth sin el encabezado.

Agregar servidores MCP desde configuración JSON

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

1. Agregar un servidor MCP desde JSON

# 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

2. Verificar que el servidor fue agregado

claude mcp get weather-api

[!TIP]

Consejos:

• Asegúrese de que el JSON esté correctamente escapado en su shell
• El JSON debe cumplir con el esquema de configuración del servidor MCP
• Puede usar --scope user para agregar el servidor a su configuración de usuario en lugar de la específica del proyecto

Importar servidores MCP desde Claude Desktop

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

1. Importar servidores desde Claude Desktop

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

2. Seleccionar qué servidores importar

Después de ejecutar el comando, verá un diálogo interactivo que le permite seleccionar qué servidores desea importar.

3. Verificar que los servidores fueron importados

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

[!TIP]

Consejos:

• Esta característica solo funciona en macOS y Windows Subsystem for Linux (WSL)
• Lee el archivo de configuración de Claude Desktop desde su ubicación estándar en esas plataformas
• Use la bandera --scope user para agregar servidores a su configuración de usuario
• Los servidores importados mantienen los mismos nombres que en Claude Desktop cuando el nombre contiene solo letras, números, guiones y guiones bajos. Claude Code reporta un servidor cuyo nombre contiene cualquier otro carácter y lo omite
• Si ya existen servidores con los mismos nombres, obtendrán un sufijo numérico (por ejemplo, server_1)

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:

1. Configurar servidores MCP en claude.ai

Añada servidores en claude.ai/customize/connectors. En planes Team y Enterprise, solo los administradores pueden añadir servidores.

2. Autenticar el servidor MCP

Complete los pasos de autenticación requeridos en claude.ai.

3. Ver y gestionar servidores en Claude Code

En Claude Code, use el comando:

/mcp

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

Anthropic también proporciona algunos conectores por sí misma, sin que tú o un administrador los agreguen. En cuentas donde Claude Docs está disponible, /mcp enumera claude.ai Claude Docs sin configuración, y Claude lo usa cuando le pides un documento destinado a otras personas. Para desactivar solo este conector, consulta 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 cómo 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 tu sesión, porque solo algunas sesiones obtienen conectores de claude.ai por sí mismas. Cada fila a continuación indica cómo llegan los conectores a 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 se están implementando 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 pide confirmación en cada llamada con el motivo Your organization requires approval for this tool. La solicitud aparece incluso en los modos de permisos acceptEdits, auto y bypassPermissions. En la terminal, la solicitud no tiene ninguna opción para recordar tu elección. Las reglas de permitir que coinciden con la herramienta tampoco omiten la solicitud. En el modo dontAsk, que nunca pide confirmación, Claude Code deniega 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

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

Puedes 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": {}
    }
  }
}

[!WARNING]

Configuración de la ruta del ejecutable: el campo command debe hacer referencia al ejecutable de Claude Code. Si el comando claude no está en la ruta del sistema, deberás especificar la ruta completa al ejecutable.

Para encontrar la ruta completa:

which claude

Luego usa la ruta completa en tu configuración:

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

Sin la ruta correcta del ejecutable, encontrarás errores como spawn claude ENOENT.

[!TIP]

Consejos:

• En Claude Desktop, intenta pedirle a Claude que lea archivos en un directorio, realice ediciones y más.
• Este servidor MCP solo expone las herramientas de Claude Code a tu cliente MCP, por lo que tu propio cliente es responsable de implementar la confirmación del usuario para llamadas a herramientas individuales.

Leer la salida de un comando en segundo plano como cliente MCP

Un campo backgroundOutputPath en un resultado de Bash o PowerShell de claude mcp serve significa que la llamada dejó su comando ejecutándose en segundo plano. Un comando se ejecuta en segundo plano cuando tu cliente establece run_in_background: true en la llamada. Un comando en primer plano también puede pasar a segundo plano cuando se agota su tiempo de espera.

El campo está en el texto JSON del resultado y contiene la ruta del archivo de salida del comando.

• Para leer la salida hasta el momento: abre el archivo en esa ruta desde tu cliente, o pasa la ruta como file_path a la herramienta Read del servidor
• Para saber cuándo ha terminado el comando: agrega un echo de una cadena fija al valor de command, como en npm test; echo DONE. El comando ha terminado una vez que esa cadena aparece en el archivo. Sin la cadena, nada marca el final, porque Claude Code no agrega ninguna línea de cierre al archivo y no notifica a tu cliente.
• Para leer el final de una salida larga: Read con solo file_path devuelve la primera página, o falla cuando el archivo excede el límite de tamaño. Pasa también offset y limit, lo cual funciona con cualquier tamaño de archivo:
  1. Llama a Read con offset y limit establecidos ambos en 1, y toma totalLines del resultado
  2. Llama a Read de nuevo con offset establecido en totalLines menos nueve y limit establecido en 10
  3. Busca tu cadena de echo en las últimas diez líneas, que devuelve la segunda llamada

El campo backgroundOutputPath requiere Claude Code v2.1.295 o posterior.

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 tu 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: puedes 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 del valor en que esté configurado MAX_MCP_OUTPUT_TOKENS. Las herramientas que devuelven datos de imagen siguen estando sujetas a MAX_MCP_OUTPUT_TOKENS
• Superando el límite: cuando un resultado exitoso sin contenido de imagen excede el límite de tokens, 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/.
• Tamaño de respuesta de servidores HTTP y SSE: cuando una respuesta de un servidor HTTP o SSE supera los 16 MiB, Claude Code deja de leerla y la solicitud falla. El límite se aplica después de la descompresión a un cuerpo de respuesta JSON o a un evento de un flujo de eventos. Si mantienes el servidor, devuelve menos datos por respuesta para mantenerte por debajo del límite, por ejemplo, paginando los resultados
• Tamaño de mensaje de servidores WebSocket: cuando un servidor WebSocket envía un mensaje de más de 16 MiB, Claude Code cierra la conexión y las llamadas en curso en ese servidor fallan. Si mantienes el servidor, devuelve menos datos por mensaje para mantenerte por debajo del límite

Una llamada que Claude Code ha movido a una tarea en segundo plano informa su resultado a través de la notificación de la tarea. Se aplican dos límites más a una llamada que se completa en primer plano:

• Límite de caracteres para resultados de texto: para una herramienta que no declara anthropic/maxResultSizeChars, Claude Code guarda en un archivo un resultado exitoso sin contenido de imagen una vez que supera los 50,000 caracteres, sin importar su cantidad de tokens. Configurar MAX_MCP_OUTPUT_TOKENS no cambia este umbral
• Resultados de error: cuando una herramienta devuelve un resultado marcado con isError: true, Claude recibe el texto del resultado como el mensaje de error de la herramienta. Un texto de error de más de unos 11,000 caracteres conserva solo sus primeros 5,000 y sus últimos 5,000 caracteres, con un marcador entre ellos que indica cuántos caracteres se eliminaron

Para cambiar el límite de tokens, establece MAX_MCP_OUTPUT_TOKENS en tu shell antes de iniciar Claude Code:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Aumentar el límite para una herramienta específica

Si estás creando un servidor MCP, puedes permitir que herramientas individuales devuelvan resultados más grandes que el umbral predeterminado de persistencia en disco de 50,000 caracteres 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 exitosos 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 desactivas 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

[!NOTE]

Si tu sesión falla con un error 400 que nombra una herramienta por su posición, sigue los pasos de Tool input schema is invalid.

Si una de las herramientas de tu servidor MCP tiene un esquema de entrada que incumple alguna de las dos reglas que aplica la API, Claude Code excluye esa herramienta. Las otras herramientas del servidor no se ven afectadas. Claude Code comprueba ambas reglas mientras carga las herramientas del servidor:

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

Cuando la obtención de banderas de características está desactivada o las banderas nunca han llegado, como en una máquina aislada, una herramienta que incumple una regla no se excluye:

• Claude recibe la herramienta sin cambios, y el registro del servidor anota input schema would be rejected by the Anthropic API para ella
• Si luego la API rechaza el esquema, consulta Herramientas cuyo esquema de entrada rechaza la API

Antes de v2.1.216, ningún despliegue 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.

Herramientas cuyo esquema de entrada rechaza la API

Si una línea del registro de depuración contiene the API refused this tool's input schema, nombra una herramienta cuyo esquema la API rechazó en una solicitud. Claude Code vuelve a enviar esa solicitud con la herramienta declarada sin parámetros.

• Si tu sesión falla con un error 400 que nombra una herramienta por su posición: sigue los pasos de Tool input schema is invalid
• Si usas el servidor: no necesitas hacer nada. Claude aún puede llamar a la herramienta, pero no ve sus parámetros
• Si mantienes el servidor: corrige el esquema de entrada de la herramienta en el servidor. La línea del registro termina con The API said: y el motivo por el que la API rechazó el esquema. Valida los argumentos que recibe el servidor, porque Claude llama a la herramienta sin ver sus parámetros

Antes de v2.1.300, cada turno que incluía el esquema rechazado fallaba con un error 400 que nombra la herramienta por su posición.

Herramientas con nombres de más de 128 caracteres

Si /mcp muestra una herramienta que Claude no puede llamar, verifica si el nombre completo de la herramienta tiene más de 128 caracteres. Ejecuta /mcp en tu sesión y selecciona la herramienta para ver su nombre completo, como mcp__<server>__<tool>. Claude Code omite una herramienta MCP de las herramientas que envía a Claude cuando su nombre completo supera los 128 caracteres. La API de Claude rechaza una solicitud que incluya una herramienta así, por lo que omitir la herramienta permite que las demás herramientas del servidor sigan funcionando.

Para ver el mensaje que nombra la herramienta y las formas de acortar su nombre completo, consulta Nombre de herramienta MCP de más de 128 caracteres.

Requerir aprobación para una herramienta específica

Si estás construyendo un servidor MCP, puedes 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 la solicitud de permiso de esa herramienta en cada llamada, incluso en los modos de permisos acceptEdits, auto y bypassPermissions, y no ofrece una opción "no volver a preguntar" para ella. Las reglas de permitir que coinciden con la herramienta tampoco omiten la solicitud. En modo dontAsk, que nunca pide confirmación, Claude Code deniega la llamada en su lugar.

La solicitud tiene que llegar a una persona. En modo no interactivo con --permission-prompt-tool, un resultado allow de la herramienta de solicitud de permisos 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 tu aplicación SDK se las muestre a un usuario.

Usa esto para herramientas cuya solicitud de permiso es en sí el objetivo, como un paso de consentimiento o de concesión de acceso donde la aprobación automática significaría que ningún humano estuvo de acuerdo. Otras herramientas del mismo servidor mantienen su comportamiento de permisos 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
  }
}

Algunas superficies, como Remote Control y las aplicaciones construidas sobre el Agent SDK, normalmente te permiten aprobar llamadas a herramientas con un toque. Para una herramienta marcada con esta anotación, Claude Code retiene la acción de un toque y, en su lugar, muestra la solicitud de permiso completa de la herramienta, por lo que la aprobación sigue viniendo de una persona que responde a la solicitud y no 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 la terminal pueda renderizar completamente, como una que incluye una advertencia de seguridad o una opción de permitir siempre que la superficie remota no puede mostrar. Respondes esa solicitud en el diálogo de la terminal en lugar de desde Remote Control.

Marca las herramientas que es seguro llamar dos veces

Si creas un servidor MCP, marca las herramientas que es seguro llamar dos veces para que Claude Code pueda repetir una llamada que estaba pendiente cuando se cerró una conexión. Claude Code puede repetir una llamada de ese tipo a un servidor HTTP o a un conector de claude.ai una vez, en una nueva conexión. Una llamada que Claude Code no repite puede fallar con connection closed before the tool call was answered.

Para marcar una herramienta, establece una de estas annotations en true en su entrada de tools/list:

• idempotentHint: la herramienta puede cambiar algo, y llamarla de nuevo con los mismos argumentos es seguro
• readOnlyHint: la herramienta no cambia nada. Claude Code también ejecuta las llamadas a la herramienta en paralelo con otras llamadas de solo lectura.

Por ejemplo, estos campos en una entrada de tools/list marcan la herramienta set_issue_status como segura de repetir:

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

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 deseas abrir un enlace en tu navegador. 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.

Modos de elicitación que declara Claude Code

Si creas un servidor MCP, las capacidades de cliente que Claude Code envía al conectarse le indican a tu servidor qué modos de elicitación puede solicitar. Claude Code declara elicitation: {form: {}, url: {}} en las siguientes conexiones, por lo que un servidor en cualquiera de ellas puede solicitar ambos modos:

• Conexiones que utilizan la revisión de protocolo 2026-07-28
• Conexiones con las revisiones de protocolo anteriores, 2025-11-25 y más antiguas, a los servidores stdio, sse, http y ws de la configuración MCP de Claude Code de un usuario. Requiere Claude Code v2.1.287 o posterior

En sus demás conexiones con las revisiones anteriores, como con los conectores de claude.ai, Claude Code declara el elicitation: {} simple, que permite solicitudes de elicitación solo en modo de formulario.

Un servidor creado con Java MCP SDK 0.17.0 o anterior puede rechazar una declaración que contenga form y url. Consulta MCP server rejected the elicitation capability.

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

1. Listar recursos disponibles

Escriba @ en su indicación para ver los recursos disponibles de todos los servidores MCP conectados. Los recursos aparecen junto a los archivos en el menú de autocompletado.

2. Referenciar un recurso específico

Utilice el formato @server:protocol://resource/path para referenciar un recurso:

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

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

3. Referencias de múltiples recursos

Puede referenciar múltiples recursos en una sola indicación:

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

[!TIP]

Consejos:

• Los recursos se obtienen automáticamente e incluyen como adjuntos cuando se referencian
• Las rutas de recursos se pueden buscar de forma difusa en el autocompletado de menciones @
• Claude Code proporciona automáticamente herramientas para listar y leer recursos MCP cuando los servidores las admiten
• Los recursos pueden contener cualquier tipo de contenido que proporcione el servidor MCP (texto, JSON, datos estructurados, etc.)

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 bajo el uso de contexto MCP al diferir las definiciones de herramientas hasta que Claude las necesita. Solo los nombres de herramientas y las 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 tu ventana de contexto. Claude Code no impone un límite fijo de herramientas por servidor; el límite práctico es tu presupuesto de ventana de contexto.

[!NOTE]

La búsqueda de herramientas no es compatible con los despliegues de Microsoft Foundry alojados en Azure, que la rechazan del lado del servidor: Claude Code detecta el rechazo y, en su lugar, carga las herramientas MCP por adelantado para ese despliegue. ENABLE_TOOL_SEARCH no puede sobrescribir esto, ya que el rechazo proviene del propio despliegue.

Búsqueda de herramientas para autores de servidores MCP

Si estás 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 tus herramientas, de manera similar a cómo funcionan los skills.

Agrega instrucciones de servidor claras y descriptivas que expliquen:

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

Claude Code corta una descripción de herramienta o las instrucciones del servidor que superen estos límites predeterminados, y Claude solo ve el texto anterior al corte:

• Instrucciones del servidor y la descripción de una herramienta que se carga por adelantado: 4.096 caracteres
• La descripción de una herramienta que Claude carga a través de la búsqueda de herramientas: 16.384 caracteres

Mantén concisas las descripciones y las instrucciones, y coloca los detalles críticos cerca del inicio. Cuando la búsqueda de herramientas compara la consulta de Claude con la descripción de una herramienta, solo lee la parte que está dentro del límite más corto, así que coloca también cerca del inicio las palabras que Claude buscaría. Una herramienta se carga por adelantado y mantiene el límite más corto siempre que no esté diferida, por ejemplo cuando la búsqueda de herramientas está desactivada, cuando la herramienta está marcada para cargarse por adelantado o cuando su servidor está exento del diferimiento.

Antes de v2.1.296, el límite más corto era de 2.048 caracteres, y antes de v2.1.295 se aplicaba a todas las descripciones de herramientas, incluidas las que se cargan a través de la búsqueda de herramientas.

Cambiar los límites de longitud de las descripciones

Para cambiar los límites predeterminados de 4.096 y 16.384 caracteres para los servidores MCP de tu sesión, establece CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH en un número de caracteres. Claude Code usa ese número para ambos límites. Con 8192, por ejemplo, aumentas el límite de 4.096 caracteres para las instrucciones del servidor y las descripciones de herramientas que se cargan por adelantado, y reduces el límite de 16.384 caracteres para las descripciones de herramientas que se cargan a través de la búsqueda de herramientas. Esta variable requiere Claude Code v2.1.280 o posterior.

Las descripciones y las instrucciones de algunos de los servidores MCP que Anthropic aloja en api.anthropic.com llegan completas a Claude, y establecer esta variable no las corta.

Marcar una herramienta para que se cargue por adelantado o permanezca diferida

Para controlar cómo se carga una de las herramientas de tu servidor, establece "anthropic/alwaysLoad" en el objeto _meta de esa herramienta. La persona que agrega tu servidor a Claude Code también puede establecer alwaysLoad para todo el servidor en su configuración, y su ajuste puede sobrescribir el tuyo:

La siguiente entrada de tools/list solicita que una herramienta se cargue por adelantado:

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

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.

Configurar CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantiene la búsqueda de herramientas desactivada. No puedes sobrescribirlo configurando ENABLE_TOOL_SEARCH tú mismo. En Claude Code v2.1.227 o posterior, tu organización puede mantener la búsqueda de herramientas activada bajo esta variable a través de la configuración administrada. En una sesión que obtiene la configuración HIPAA, la búsqueda de herramientas está desactivada, y ni ENABLE_TOOL_SEARCH ni la configuración administrada la vuelven a activar. Deshabilitar capacidades de pre-lanzamiento cubre dónde se aplica la sobrescritura y qué elimina la variable.

Claude Code usa la búsqueda de herramientas en Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5 y modelos posteriores, o en Opus 4.5, Sonnet 4.5, Haiku 4.5 y modelos posteriores en Agent Platform de Google Cloud. En modelos anteriores, Claude Code carga todas las herramientas MCP por adelantado, y ENABLE_TOOL_SEARCH=true no sobrescribe esto.

En Agent Platform de Google Cloud, Claude Code decide según la generación del 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 sobrescribe 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 configuraras ENABLE_TOOL_SEARCH=true.

Controla el comportamiento de la 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 establece el valor en el campo env de tu settings.json.

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

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

Si deniegas ToolSearch o lo omites de --tools, las herramientas MCP se cargan por adelantado en su lugar, pero una solicitud aún puede llevar una entrada defer_loading de marcador de posición. Si un gateway rechaza esa entrada, consulta Búsqueda de herramientas a través de un gateway de LLM.

Búsqueda de herramientas a través de un gateway de LLM

[!NOTE]

Estos casos se tratan en otros lugares:

• Configuraste CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: consulta cómo afecta a la búsqueda de herramientas
• Una solicitud falló con un error que menciona defer_loading o tool_reference: consulta Extra inputs are not permitted

Cuando ANTHROPIC_BASE_URL apunta a un gateway, la búsqueda de herramientas está activada de forma predeterminada, por lo que las solicitudes incluyen campos de herramienta defer_loading y bloques tool_reference para que el gateway los reenvíe. Mientras la búsqueda de herramientas está activada, las herramientas MCP se difieren. Para cargar todas las herramientas por adelantado en su lugar, establece ENABLE_TOOL_SEARCH=false en tu shell o en el env de tu configuración. Antes de v2.1.304, la búsqueda de herramientas estaba desactivada detrás de un gateway a menos que ENABLE_TOOL_SEARCH fuera true, auto o auto:N.

En v2.1.305 o posterior, Claude Code puede reintentar una solicitud sin búsqueda de herramientas después de un 400 o 422 cuya causa no reconoce. Cuando el reintento funciona, no aparece nada en pantalla y no necesitas hacer nada: las herramientas MCP se cargan por adelantado en su lugar. Claude Code vuelve a intentar la búsqueda de herramientas más tarde, a costa de otra solicitud rechazada. Para omitir esas solicitudes, establece ENABLE_TOOL_SEARCH=false.

Herramientas que permanecen diferidas por debajo del umbral de ENABLE_TOOL_SEARCH=auto

Si /context etiqueta herramientas como (deferred) o (loaded on-demand) aunque sus definiciones totalicen menos que el umbral de auto, la búsqueda de herramientas ya estaba activada en esta conversación y siguió activada. El total puede bajar más tarde, por ejemplo mientras los servidores MCP se reconectan después de que reanudas una sesión. No necesitas hacer nada: Claude carga cada una de esas herramientas cuando una tarea la necesita.

Eximir un servidor del diferimiento

Si las herramientas de un servidor siempre deben ser visibles para Claude sin un paso de búsqueda, establece alwaysLoad en true en la configuración de ese servidor. Las herramientas del servidor se cargan entonces en el contexto independientemente del ajuste ENABLE_TOOL_SEARCH. Úsalo para un pequeño número de herramientas que Claude necesita en cada turno, ya que cada herramienta cargada por adelantado consume contexto que de otro modo estaría disponible para tu conversación.

La siguiente entrada de .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.

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 prompt. 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; establece MCP_CONNECTION_NONBLOCKING=0 para que el inicio también los espere.

Diferir las herramientas de un servidor

Para mantener todas las herramientas de un servidor detrás de la búsqueda de herramientas, establece "alwaysLoad": false en la entrada de ese servidor en tu configuración MCP. Eso incluye las herramientas que el autor del servidor ha marcado para cargarse por adelantado. Si omites alwaysLoad, esas herramientas marcadas se cargan por adelantado. Requiere Claude Code v2.1.287 o posterior.

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

1. Descubrir prompts disponibles

Escriba / para ver los comandos disponibles para usted, incluidos los de los servidores MCP. Claude Code enumera cada prompt de MCP como /servername:promptname (MCP). Escribir /mcp__servername__promptname también lo ejecuta.

2. Ejecutar un prompt sin argumentos

/mcp__github__list_prs

3. Ejecutar un prompt con argumentos

Muchos prompts aceptan argumentos. Páselos separados por espacios después del comando. Claude Code divide los argumentos en espacios en blanco, por lo que cada argumento es un único token:

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

[!TIP]

Consejos:

• Los prompts de MCP se descubren dinámicamente desde los servidores conectados
• Los argumentos se analizan según los parámetros definidos del prompt
• Los resultados del prompt se inyectan directamente en la conversación
• En la forma /mcp__servername__promptname, Claude Code reemplaza cualquier carácter en el nombre del servidor fuera de A-Z, a-z, 0-9, _ y - con _, y utiliza el nombre del prompt tal como lo declara el servidor

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.