58 58
59Claude le pregunta sobre su caso de uso y crea un servidor HTTP remoto o un servidor stdio local.59Claude le pregunta sobre su caso de uso y crea un servidor HTTP remoto o un servidor stdio local.
60 60
61## Instalación de servidores MCP61## Instalar servidores MCP
62 62
63Los servidores MCP se pueden configurar de varias formas según tus necesidades:63Los servidores MCP se pueden configurar de varias maneras según tus necesidades:
64 64
65### Opción 1: Agregar un servidor HTTP remoto65### Opción 1: Agregar un servidor HTTP remoto
66 66
67Los 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.67Los servidores HTTP son la opción recomendada para conectarte a servidores MCP remotos. Es el transporte más ampliamente compatible para servicios basados en la nube.
68 68
69```bash theme={null}69```bash theme={null}
70# Sintaxis básica70# Basic syntax
71claude mcp add --transport http <name> <url>71claude mcp add --transport http <name> <url>
72 72
73# Ejemplo real: Conectar a Notion73# Real example: Connect to Notion
74claude mcp add --transport http notion https://mcp.notion.com/mcp74claude mcp add --transport http notion https://mcp.notion.com/mcp
75 75
76# Ejemplo con token Bearer76# Example with Bearer token
77claude mcp add --transport http secure-api https://api.example.com/mcp \77claude mcp add --transport http secure-api https://api.example.com/mcp \
78 --header "Authorization: Bearer your-token"78 --header "Authorization: Bearer your-token"
79```79```
80 80
81Al 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.81Cuando configuras servidores MCP mediante JSON en `.mcp.json`, `~/.claude.json` o `claude mcp add-json`, el campo `type` acepta `streamable-http` como alias de `http`. La especificación de MCP usa el nombre `streamable-http` para este transporte, por lo que las configuraciones copiadas de la documentación de un servidor funcionan sin modificaciones.
82 82
83Una 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`.83Una entrada JSON que tiene `url` pero no `type` es un error de configuración, porque Claude Code interpreta 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`.
84 84
85Solo una aplicación host SDK, como una aplicación [Agent SDK](https://code.claude.com/docs/es/agent-sdk/mcp.md) o la [aplicación de escritorio](https://code.claude.com/docs/es/desktop.md), 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`.85Solo una aplicación host del SDK, como una aplicación del [Agent SDK](https://code.claude.com/docs/es/agent-sdk/mcp.md) o la [aplicación de escritorio](https://code.claude.com/docs/es/desktop.md), puede registrar un servidor en proceso `"type": "sdk"`. 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`.
86 86
87> [!NOTE]87> [!NOTE]
88>88>
89> 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`](https://code.claude.com/docs/es/headless#stream-responses) del evento `system/init`, para que los scripts puedan detectar que el servidor nunca se cargó.89> En ejecuciones con `--output-format stream-json`, Claude Code también informa una entrada de `--mcp-config` omitida en el [campo `mcp_server_errors`](https://code.claude.com/docs/es/headless#stream-responses) del evento `system/init`, para que los scripts puedan detectar que el servidor nunca se cargó.
90 90
91### Opción 2: Agregar un servidor SSE remoto91### Opción 2: Agregar un servidor SSE remoto
92 92
94>94>
95> El transporte SSE (Server-Sent Events) está obsoleto. Usa servidores HTTP en su lugar, cuando estén disponibles.95> El transporte SSE (Server-Sent Events) está obsoleto. Usa servidores HTTP en su lugar, cuando estén disponibles.
96 96
97Algunos 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](#option-1-add-a-remote-http-server). 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.97Algunos servicios todavía exponen solo un endpoint SSE. Agrégalos con el mismo comando `claude mcp add --transport http <name> <url>` que [un servidor HTTP](#option-1-add-a-remote-http-server). Claude Code prueba primero el transporte HTTP y cambia a SSE cuando el servidor no lo acepta. El cambio automático requiere Claude Code v2.1.265 o posterior.
98 98
99En una versión anterior, o para conectarte sobre SSE directamente, pasa `--transport sse` en su lugar:99En una versión anterior, o para conectarte directamente por SSE, pasa `--transport sse` en su lugar:
100 100
101```bash theme={null}101```bash theme={null}
102# Sintaxis básica102# Basic syntax
103claude mcp add --transport sse <name> <url>103claude mcp add --transport sse <name> <url>
104 104
105# Ejemplo real: Conectar a Asana105# Real example: Connect to Asana
106claude mcp add --transport sse asana https://mcp.asana.com/sse106claude mcp add --transport sse asana https://mcp.asana.com/sse
107 107
108# Ejemplo con encabezado de autenticación108# Example with authentication header
109claude mcp add --transport sse private-api https://api.company.com/sse \109claude mcp add --transport sse private-api https://api.company.com/sse \
110 --header "X-API-Key: your-key-here"110 --header "X-API-Key: your-key-here"
111```111```
112 112
113### Opción 3: Agregar un servidor stdio local113### Opción 3: Agregar un servidor stdio local
114 114
115Los servidores stdio se ejecutan como procesos locales en tu máquina. Son ideales para herramientas que necesitan acceso directo al sistema o scripts personalizados.115Los servidores stdio se ejecutan como procesos locales en tu máquina. Son ideales para herramientas que necesitan acceso directo al sistema o para scripts personalizados.
116 116
117Claude 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.117Claude Code establece `CLAUDE_PROJECT_DIR` en el entorno del servidor iniciado con la raíz del proyecto, para que tu servidor pueda resolver rutas relativas al proyecto sin depender del directorio de trabajo. Es el mismo directorio que reciben los hooks en su variable `CLAUDE_PROJECT_DIR`. Léela desde dentro del proceso de tu servidor, por ejemplo `process.env.CLAUDE_PROJECT_DIR` en Node u `os.environ["CLAUDE_PROJECT_DIR"]` en Python.
118 118
119`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](https://code.claude.com/docs/es/permissions.md#working-directories) que hayas otorgado con `--add-dir`, `/add-dir`, o el ajuste `additionalDirectories`. Claude Code envía `notifications/roots/list_changed` cuando ese conjunto cambia.119`CLAUDE_PROJECT_DIR` es la raíz estable del proyecto y no cambia cuando agregas o quitas directorios de trabajo a mitad de la sesión. Un servidor que limita su propio acceso al sistema de archivos a un conjunto de directorios permitidos debería implementar en su lugar la solicitud MCP `roots/list`. Claude Code responde a `roots/list` con el directorio de inicio de la sesión más cada [directorio de trabajo adicional](https://code.claude.com/docs/es/permissions.md#working-directories) que hayas concedido con `--add-dir`, `/add-dir` o el ajuste `additionalDirectories`. Claude Code envía `notifications/roots/list_changed` cuando ese conjunto cambia.
120 120
121Esta 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.121Esta variable se establece en el entorno del servidor, no en el propio entorno de Claude Code, por lo que referenciarla mediante la expansión `${VAR}` en el `command` o los `args` de una entrada de `.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.
122 122
123```bash theme={null}123```bash theme={null}
124# Sintaxis básica124# Basic syntax
125claude mcp add [options] <name> -- <command> [args...]125claude mcp add [options] <name> -- <command> [args...]
126 126
127# Ejemplo real: Agregar servidor Airtable127# Real example: Add Airtable server
128claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \128claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
129 -- npx -y airtable-mcp-server129 -- npx -y airtable-mcp-server
130```130```
131 131
132> [!NOTE]132> [!NOTE]
133>133>
134> 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.134> Para los 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 va después de `--` se pasa al servidor sin cambios.
135>135>
136> Por ejemplo:136> Por ejemplo:
137>137>
138> * `claude mcp add --transport stdio myserver -- npx server` → ejecuta `npx server`138> * `claude mcp add --transport stdio myserver -- npx server` → ejecuta `npx server`
139> * `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 entorno139> * `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
140>140>
141> Sin `--`, Claude Code intentaría analizar los flags del servidor, como `--port` arriba, como sus propias opciones.141> Sin `--`, Claude Code intentaría interpretar los flags del servidor, como `--port` arriba, como sus propias opciones.
142>142>
143> `--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.143> `--env` acepta varios pares `KEY=value`. Si el nombre del servidor va directamente después de `--env`, la CLI interpreta 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.
144 144
145#### Cómo Claude Code detiene un servidor stdio145#### Cómo detiene Claude Code un servidor stdio
146 146
147Cuando 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:147Cuando 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 salga 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:
148 148
149* **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.149* **En macOS y Linux**: Claude Code envía `SIGINT`, luego `SIGTERM` si el proceso sigue en ejecución 100 milisegundos después, y luego `SIGKILL` tras otros 400 milisegundos.
150* **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.150* **En Windows**: Claude Code cierra el stdin del servidor y luego termina el árbol de procesos del servidor si el proceso sigue en ejecución 300 milisegundos después.
151 151
152Antes de v2.1.296, Claude Code en Windows finalizaba el árbol de procesos del servidor de inmediato, sin cerrar primero stdin ni esperar.152Antes de v2.1.296, Claude Code en Windows terminaba el árbol de procesos del servidor de inmediato, sin cerrar primero el stdin ni esperar.
153 153
154### Opción 4: Agregar un servidor WebSocket remoto154### Opción 4: Agregar un servidor WebSocket remoto
155 155
156Los 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.156Los servidores WebSocket mantienen una conexión bidireccional persistente, lo que conviene a servidores MCP remotos que envían eventos a Claude sin que se los pidan. Usa HTTP en su lugar cuando tu servidor solo responde a solicitudes, ya que HTTP admite OAuth y el flag `claude mcp add --transport`, mientras que WebSocket no admite ninguno de los dos.
157 157
158Configura servidores WebSocket en `.mcp.json` o con `claude mcp add-json`:158Configura los servidores WebSocket en `.mcp.json` o con `claude mcp add-json`:
159 159
160```bash theme={null}160```bash theme={null}
161claude mcp add-json events-server \161claude mcp add-json events-server \
162 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'162 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'
163```163```
164 164
165La 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`](#use-dynamic-headers-for-custom-authentication). El flag `claude mcp add --transport` no acepta `ws`.165La entrada `type: "ws"` acepta los mismos campos `url`, `headers`, `headersHelper`, `timeout` y `alwaysLoad` que `http`. La autenticación es solo por encabezados, así que pasa un token estático en `headers` o genera uno al conectarte con [`headersHelper`](#use-dynamic-headers-for-custom-authentication). El flag `claude mcp add --transport` no acepta `ws`.
166 166
167### Agregar un servidor desde instrucciones de configuración escritas para otro cliente167### Agregar un servidor a partir de instrucciones de configuración escritas para otro cliente
168 168
169Los 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:169Los 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 incluir ningún comando `claude mcp add`. Para agregar el servidor de todos modos, busca en esas instrucciones una URL, un comando de inicio o un bloque JSON:
170 170
171* **Una URL** como `https://mcp.example.com/mcp`: el servidor es remoto.171* **Una URL** como `https://mcp.example.com/mcp`: el servidor es remoto.
172* **Un comando de lanzamiento** como `npx -y @example/mcp-server`: el servidor se ejecuta en tu máquina.172* **Un comando de inicio** como `npx -y @example/mcp-server`: el servidor se ejecuta en tu máquina.
173* **Un bloque JSON `mcpServers`**: configuración escrita para el archivo de configuración de otro cliente.173* **Un bloque JSON `mcpServers`**: configuración escrita para el archivo de configuración de otro cliente.
174 174
175Cada uno es una de las entradas que toman las cuatro opciones en [Instalación de servidores MCP](#installing-mcp-servers). Encuentra a continuación la forma que tienes para convertirla en el comando que Claude Code acepta. Cada comando escribe en [alcance local](#local-scope) a menos que agregues `--scope project` o `--scope user`.175Cada uno es una de las entradas que aceptan las cuatro opciones de [Instalar servidores MCP](#installing-mcp-servers). Busca a continuación la forma que tienes para convertirla en el comando que acepta Claude Code. Cada comando escribe en el [alcance local](#local-scope) a menos que agregues `--scope project` o `--scope user`.
176 176
177#### Agregar un servidor desde una URL177#### Agregar un servidor a partir de una URL
178 178
179Una URL significa que el servidor es remoto. Para un endpoint `https://`, agrégalo con `--transport http`, o sigue la [Opción 2](#option-2-add-a-remote-sse-server) cuando las instrucciones digan que el endpoint usa SSE. Para un endpoint `wss://`, usa la [Opción 4](#option-4-add-a-remote-websocket-server) en su lugar, ya que `--transport` no acepta `ws`:179Una URL significa que el servidor es remoto. Para un endpoint `https://`, agrégalo con `--transport http`, o sigue la [Opción 2](#option-2-add-a-remote-sse-server) cuando las instrucciones digan que el endpoint usa SSE. Para un endpoint `wss://`, usa la [Opción 4](#option-4-add-a-remote-websocket-server) en su lugar, ya que `--transport` no acepta `ws`:
180 180
182claude mcp add --transport http example https://mcp.example.com/mcp182claude mcp add --transport http example https://mcp.example.com/mcp
183```183```
184 184
185Si 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](#option-1-add-a-remote-http-server).185Si las instrucciones también indican una clave de API o un encabezado de token, pásalo con `--header` como se muestra en la [Opción 1](#option-1-add-a-remote-http-server).
186 186
187#### Agregar un servidor desde un comando `npx`, `uvx`, o binario187#### Agregar un servidor a partir de un comando `npx`, `uvx` o binario
188 188
189Un 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 `--`:189Un comando de inicio significa que el servidor se ejecuta como un proceso stdio local. Coloca el comando completo después de `--`, para que Claude Code pase flags como `-y` al comando que inicia el servidor en lugar de interpretarlos como sus propias opciones. Pasa con `--env` cualquier variable de entorno que pidan las instrucciones, después del nombre del servidor y antes de `--`:
190 190
191```bash theme={null}191```bash theme={null}
192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server
193```193```
194 194
195La [Opción 3](#option-3-add-a-local-stdio-server) cubre el separador `--` en su totalidad.195La [Opción 3](#option-3-add-a-local-stdio-server) explica en detalle el separador `--`.
196 196
197#### Agregar un servidor desde un bloque JSON `mcpServers`197#### Agregar un servidor a partir de un bloque JSON `mcpServers`
198 198
199Un 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:199Un bloque `mcpServers` escrito para otro cliente MCP, como Claude Desktop, usa la clave contenedora y la forma de entrada que lee Claude Code. Pasa a `claude mcp add-json` el objeto que está dentro de `mcpServers`, no el contenedor. Dos tipos de entradas necesitan una corrección primero:
200 200
201* **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.201* **Una `url` sin `type`**: agrega `"type": "http"`, `"type": "sse"` o `"type": "ws"` según el endpoint. Claude Code interpreta una entrada sin `type` como un servidor stdio, por lo que una entrada con `url` sin `type` falla.
202* **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.202* **Una clave con caracteres distintos de letras, números, guiones y guiones bajos**: elige un nombre de servidor que use solo esos caracteres. En caso contrario, la clave es el nombre del servidor.
203 203
204Por ejemplo, este bloque:204Por ejemplo, este bloque:
205 205
220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
221```221```
222 222
223[Agregar servidores MCP desde configuración JSON](#add-mcp-servers-from-json-configuration) 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](#project-scope) cubre cómo Claude Code carga y aprueba ese archivo.223[Agregar servidores MCP desde configuración JSON](#add-mcp-servers-from-json-configuration) explica el escape en el 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](#project-scope) explica cómo Claude Code carga y aprueba ese archivo.
224 224
225Cada 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](#server-status) cubre los estados que muestra y el paso de aprobación para servidores `.mcp.json`.225Cada comando `claude mcp add` y `claude mcp add-json` imprime una línea `Added ...` si tiene éxito. Para comprobar que Claude Code se conectó, ejecuta `claude mcp get <name>`; [Estado del servidor](#server-status) explica los estados que muestra y el paso de aprobación para los servidores de `.mcp.json`.
226 226
227### Administración de tus servidores227### Administrar tus servidores
228 228
229Una vez configurados, puedes administrar tus servidores MCP con estos comandos:229Una vez configurados, puedes administrar tus servidores MCP con estos comandos:
230 230
231```bash theme={null}231```bash theme={null}
232# Listar todos los servidores configurados232# List all configured servers
233claude mcp list233claude mcp list
234 234
235# Obtener detalles de un servidor específico235# Get details for a specific server
236claude mcp get notion236claude mcp get notion
237 237
238# Eliminar un servidor238# Remove a server
239claude mcp remove notion239claude mcp remove notion
240 240
241# (dentro de Claude Code) Verificar estado del servidor241# (within Claude Code) Check server status
242/mcp242/mcp
243```243```
244 244
245Cuando 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>`](#authenticate-from-the-command-line) en tu shell antes de `claude mcp remove <name>`.245Cuando eliminas un servidor remoto, Claude Code también borra los tokens de 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>`](#authenticate-from-the-command-line) en tu shell antes de `claude mcp remove <name>`.
246 246
247#### Estado del servidor247#### Estado del servidor
248 248
249`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](https://code.claude.com/docs/es/errors.md#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](https://code.claude.com/docs/es/errors.md#mcp-server-may-not-have-been-saved-or-removed).249`claude mcp add` confirma que se agregó correctamente imprimiendo una línea `Added ...`, lo que significa que se escribió la configuración. Si el comando imprime en su lugar un mensaje `was not saved`, consulta [El servidor MCP no se guardó ni se eliminó](https://code.claude.com/docs/es/errors.md#mcp-server-was-not-saved-or-removed); para un mensaje `may not have been saved`, consulta [Es posible que el servidor MCP no se haya guardado o eliminado](https://code.claude.com/docs/es/errors.md#mcp-server-may-not-have-been-saved-or-removed).
250 250
251`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.251`claude mcp list` muestra un estado de salud junto a cada servidor que lista, como `✔ Connected`, `! Needs authentication` o `✘ Failed to connect`. Un estado de fallo significa que Claude Code no pudo conectarse a ese servidor, no que el comando de listado haya fallado.
252 252
253Los 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:253Los estados de esta lista informan una decisión de configuración y no un intento de conexión, por lo que Claude Code los imprime sin conectarse al servidor:
254 254
255* ``⏸ 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.255* ``⏸ 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.
256* `✘ Rejected (see disabledMcpjsonServers in settings)`: un servidor `.mcp.json` que una entrada [`disabledMcpjsonServers`](https://code.claude.com/docs/es/settings-reference#disabledmcpjsonservers) rechaza. Claude Code lo muestra solo en `claude mcp get <name>`.256* `✘ Rejected (see disabledMcpjsonServers in settings)`: un servidor de `.mcp.json` que una entrada de [`disabledMcpjsonServers`](https://code.claude.com/docs/es/settings-reference#disabledmcpjsonservers) rechaza. Claude Code lo muestra solo en `claude mcp get <name>`.
257* `⊘ Disabled for this project (re-enable via /mcp)`: un servidor que la lista [`disabledMcpServers`](#disable-a-server-without-removing-it) 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`.257* `⊘ Disabled for this project (re-enable via /mcp)`: un servidor que nombra la lista [`disabledMcpServers`](#disable-a-server-without-removing-it) del proyecto. Claude Code lo muestra tanto en `claude mcp list` como en `claude mcp get <name>`. Vuelve a activar el servidor desde el panel `/mcp`.
258* `✘ 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](https://code.claude.com/docs/es/managed-mcp.md#how-restrictions-appear-to-users) se oculta en ambos comandos en lugar de mostrarse con este estado. Pregunta a tu administrador qué política bloquea el servidor.258* `✘ Blocked by enterprise managed policy`: un servidor que una de las políticas de tu organización rechaza. 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](https://code.claude.com/docs/es/managed-mcp.md#how-restrictions-appear-to-users) se oculta en ambos comandos en lugar de mostrarse con este estado. Pregúntale a tu administrador qué política bloquea el servidor.
259 259
260#### Aprobaciones de servidores de proyecto y confianza del espacio de trabajo260#### Aprobaciones de servidores de proyecto y confianza del espacio de trabajo
261 261
262`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`](https://code.claude.com/docs/es/settings-reference#enableallprojectmcpservers) o [`enabledMcpjsonServers`](https://code.claude.com/docs/es/settings-reference#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.262`claude mcp list` y `claude mcp get` leen las 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`](https://code.claude.com/docs/es/settings-reference#enableallprojectmcpservers) o [`enabledMcpjsonServers`](https://code.claude.com/docs/es/settings-reference#enabledmcpjsonservers) incluidos mediante commit en el `.claude/settings.json` del proyecto se ignoran en una carpeta que no es de confianza, y el servidor permanece en `⏸ Pending approval` en lugar de conectarse y pasar la comprobación de salud.
263 263
264Las aprobaciones de estas fuentes aún se aplican en una carpeta no confiable:264Las aprobaciones de estas fuentes siguen aplicándose en una carpeta que no es de confianza:
265 265
266* tu `~/.claude/settings.json` de usuario266* tu `~/.claude/settings.json` de usuario
267* configuración administrada267* la configuración administrada
268* configuración pasada con `--settings`268* la configuración pasada con `--settings`
269 269
270Claude 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](https://code.claude.com/docs/es/permissions.md#project-allow-rules-and-workspace-trust). 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`](https://code.claude.com/docs/es/env-vars). 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.270Claude Code también aplica las aprobaciones de un `.claude/settings.local.json` sin seguimiento, pero ejecuta git para comprobar si el archivo tiene seguimiento, y ejecuta esa comprobación solo en una [carpeta de confianza](https://code.claude.com/docs/es/permissions.md#project-allow-rules-and-workspace-trust). En una carpeta en la que nunca has confiado, Claude Code espera al 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`](https://code.claude.com/docs/es/env-vars). Antes de v2.1.207, Claude Code aplicaba las aprobaciones de un `.claude/settings.local.json` sin seguimiento incluso en una carpeta en la que nunca habías confiado.
271 271
272Una entrada `disabledMcpjsonServers` en cualquier archivo de configuración aún rechaza el servidor.272Una entrada `disabledMcpjsonServers` en cualquier archivo de configuración sigue rechazando el servidor.
273 273
274#### Detalle del estado del servidor274#### Detalle del estado del servidor
275 275
276En `/mcp`, incluido el menú de un servidor allí, y en el administrador [`/plugin`](https://code.claude.com/docs/es/plugins/install), 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.276En `/mcp`, incluido el menú de un servidor allí, y en el administrador de [`/plugin`](https://code.claude.com/docs/es/plugins/install), 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 sus herramientas. Las herramientas están disponibles desde tu primer mensaje, así que no necesitas hacer nada. La caché de descubrimiento y su estado `cached` requieren Claude Code v2.1.221 o posterior.
277 277
278La 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`](https://code.claude.com/docs/es/env-vars) 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.278La caché de descubrimiento está desactivada de forma predeterminada, a menos que un despliegue gradual la haya activado para tu cuenta. Establece [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/es/env-vars) para activarla, o `0` para mantenerla desactivada incluso cuando el despliegue la haya activado. Antes de v2.1.238, la caché estaba activada de forma predeterminada.
279 279
280Cuando 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é.280Cuando seleccionas **Disable** o **Clear authentication** en 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 con fallo; en un servidor `cached`, **Reconnect** conecta el servidor en ese momento y conserva 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é.
281 281
282##### Errores de conexión y servidores sin configurar282##### Fallos de conexión y servidores sin configurar
283 283
284Cuando 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:`.284Cuando el estado de un servidor es `✘ Failed to connect`, `claude mcp list` añade el detalle del fallo 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:`.
285 285
286Claude 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.286Claude 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.
287 287
288Cuando 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`.288Cuando completas la autenticación desde `/mcp` y la conexión sigue fallando con un estado HTTP o un código de error de transporte, Claude Code añade ese código y el origen de la URL 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 lo indica, como `https://mcp.example.com`.
289 289
290* La ruta y la consulta nunca aparecen en ese mensaje.290* La ruta y la consulta nunca aparecen en ese mensaje.
291* Para un servidor en el [alcance](#mcp-installation-scopes) 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.291* Para un servidor en el [alcance](#mcp-installation-scopes) 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.
292* Para una falla sin código de estado ni código de error, Claude Code muestra el texto de error sin el origen.292* Para un fallo sin estado ni código de error, Claude Code muestra el texto del error sin el origen.
293 293
294Un 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`](https://code.claude.com/docs/es/plugins/install), 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.294Un servidor remoto cuya configuración tiene una `url` vacía aparece como `not configured` en `/mcp`, en `claude mcp list` y en el administrador de [`/plugin`](https://code.claude.com/docs/es/plugins/install), 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 adelante, así que Claude Code no la 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.
295 295
296#### Advertencias de configuración296#### Advertencias de configuración
297 297
298Claude Code advierte sobre los problemas de configuración a continuación. Cada entrada dice qué verifica Claude Code y cómo eliminar la advertencia:298Claude Code advierte sobre los problemas de configuración que se indican a continuación. Cada entrada explica qué comprueba Claude Code y cómo eliminar la advertencia:
299 299
300* **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.300* **Espacios en blanco ocultos**: Claude Code advierte cuando un valor de la configuración MCP tiene espacios en blanco ocultos al principio o al final, lo que suele ocurrir al pegar un token con un salto de línea final. Claude Code comprueba `command`, `url`, cada entrada de `args`, y los valores y nombres de claves bajo `env` y `headers`. Claude Code muestra la advertencia en la salida de `claude mcp list` y en `/mcp`, nombrando los campos afectados sin mostrar sus valores, por ejemplo `Leading or trailing whitespace in: headers.Authorization`. Claude Code no recorta los espacios en blanco y usa los valores exactamente como están escritos, así que edita la configuración para eliminarlos.
301* **Mismo nombre en más de un alcance**: si defines el mismo nombre de servidor en más de un [alcance](#mcp-installation-scopes) 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}`](#environment-variable-expansion-in-mcp-json) sin expandir, por lo que nunca muestra un valor resuelto como una clave de API.301* **El mismo nombre en más de un alcance**: si defines el mismo nombre de servidor en más de un [alcance](#mcp-installation-scopes) con endpoints distintos, Claude Code advierte sobre el conflicto en la salida de `claude mcp list` y en `/mcp`. Claude Code almacena los inicios de sesión de OAuth por endpoint, así que cuando autenticas la definición que se carga en un proyecto, igual necesitas iniciar sesión por separado en un proyecto donde se cargue una definición distinta. Conserva el endpoint que quieras y elimina los demás 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}`](#environment-variable-expansion-in-mcp-json) sin expandir, por lo que nunca muestra un valor resuelto como una clave de API.
302* **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](https://code.claude.com/docs/es/desktop.md#preview-your-app).302* **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 al cargarlo y muestra una advertencia que te pide cambiarle el nombre. `claude mcp add` rechaza un nombre reservado con un error. `Claude Preview` y `Claude Browser` nombran ambos el servidor integrado que usa el [panel de vista previa de la aplicación de escritorio de Claude Code](https://code.claude.com/docs/es/desktop.md#preview-your-app).
303* **Variable de entorno faltante**: si una [referencia `${VAR}`](#environment-variable-expansion-in-mcp-json) 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](#credential-variables-that-read-as-empty) en su lugar, sin advertencia.303* **Variable de entorno faltante**: si una [referencia `${VAR}`](#environment-variable-expansion-in-mcp-json) 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 aun así 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](#credential-variables-that-read-as-empty) en su lugar, sin advertencia.
304 304
305#### Disponibilidad de herramientas305#### Disponibilidad de herramientas
306 306
307El 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.307El 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 ninguna.
308 308
309##### Recuento de herramientas en una sesión en la nube309##### Recuentos de herramientas en una sesión en la nube
310 310
311En una [sesión en la nube](https://code.claude.com/docs/es/claude-code-on-the-web.md), un recuento como `3 of 13 tools available` significa que Claude no puede usar las otras 10. Comprueba estas causas, entre otras:311En una [sesión en la nube](https://code.claude.com/docs/es/claude-code-on-the-web.md), un recuento como `3 of 13 tools available` significa que Claude no puede usar las otras 10. Comprueba estas causas, entre otras:
312 312
313* **Una regla de denegación en el `.claude/settings.json` de tu repositorio nombra la herramienta o su servidor completo**: elimina la [regla](https://code.claude.com/docs/es/permissions.md#mcp), si [tu sesión lee ese archivo](https://code.claude.com/docs/es/settings.md#settings-in-cloud-sessions)313* **Una regla de denegación en el `.claude/settings.json` de tu repositorio nombra la herramienta o su servidor completo**: elimina la [regla](https://code.claude.com/docs/es/permissions.md#mcp), si [tu sesión lee ese archivo](https://code.claude.com/docs/es/settings.md#settings-in-cloud-sessions)
314* **El nombre completo de la herramienta tiene más de 128 caracteres**: sigue [los pasos para un nombre demasiado largo](https://code.claude.com/docs/es/errors.md#mcp-tool-name-over-128-characters)314* **El nombre completo de la herramienta supera los 128 caracteres**: sigue [los pasos para un nombre demasiado largo](https://code.claude.com/docs/es/errors.md#mcp-tool-name-over-128-characters)
315* **El servidor lista la herramienta para su propia interfaz y no para Claude**: si mantienes el servidor, agrega `model` a `_meta.ui.visibility` de la herramienta para dársela a Claude. En caso contrario, no hay nada que corregir.315* **El servidor lista la herramienta para su propia interfaz y no para Claude**: si mantienes el servidor, agrega `model` al `_meta.ui.visibility` de la herramienta para darle la herramienta a Claude. De lo contrario, no hay nada que corregir.
316 316
317##### Herramientas de un servidor que aún se está conectando317##### Herramientas de un servidor que aún se está conectando
318 318
319Si 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:319Si 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 ocurre la espera depende de tu configuración:
320 320
321* **Con [búsqueda de herramientas](#scale-with-mcp-tool-search), el valor predeterminado**: la espera sucede dentro de la llamada `ToolSearch`.321* **Con [búsqueda de herramientas](#scale-with-mcp-tool-search), la opción predeterminada**: la espera ocurre dentro de la llamada a `ToolSearch`.
322* **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](#tool-search-through-a-gateway).322* **Sin búsqueda de herramientas**: Claude usa en su lugar la herramienta `WaitForMcpServers`. 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](#tool-search-through-a-gateway).
323* **En un [despliegue de Microsoft Foundry alojado en Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**: 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](#scale-with-mcp-tool-search), las herramientas de un servidor que termina de conectarse quedan disponibles en la siguiente solicitud de Claude.323* **En un [despliegue de Microsoft Foundry alojado en Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**: Claude comienza por 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 a partir de la API. Después de que Claude Code cambie ese despliegue a [carga anticipada](#scale-with-mcp-tool-search), las herramientas de un servidor que termina de conectarse quedan disponibles en la siguiente solicitud de Claude.
324 324
325Con 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.325Con la búsqueda de herramientas activada, cuando un servidor termina de conectarse mientras Claude está trabajando, Claude Code le lista a Claude los nombres de las herramientas del servidor en su siguiente solicitud dentro del mismo turno. Claude puede entonces buscar y llamar a esas herramientas sin esperar tu próximo mensaje.
326 326
327Despué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](#automatic-reconnection), la llamada falla con el [error de herramienta](https://code.claude.com/docs/es/errors.md#no-such-tool-available) `No such tool available`.327Después de reanudar una sesión, Claude puede llamar a una herramienta de la conversación guardada mientras el servidor MCP de la herramienta todavía 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](#automatic-reconnection), la llamada falla con el [error de herramienta](https://code.claude.com/docs/es/errors.md#no-such-tool-available) `No such tool available`.
328 328
329### Deshabilitar un servidor sin eliminarlo329### Desactivar un servidor sin eliminarlo
330 330
331Desactiva 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.331Desactiva un servidor en el panel `/mcp` para que Claude Code deje de conectarse a él sin perder su configuración. Claude Code sigue listando el servidor en `/mcp`, marcado como desactivado.
332 332
333Cuando 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:333Cuando 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:
334 334
335* `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](https://code.claude.com/docs/es/managed-mcp.md#provide-servers-through-managed-settings), los conectores de claude.ai que Claude Code [obtiene por sí mismo](#how-connectors-reach-claude-code), 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](#disable-claude-ai-connectors), Claude Code lo escribe en esta lista bajo su nombre visible, por ejemplo `claude.ai Slack`.335* `disabledMcpServers`: una lista de exclusión para servidores configurados por el usuario, servidores de plugins, servidores que tu organización [proporciona mediante la configuración administrada](https://code.claude.com/docs/es/managed-mcp.md#provide-servers-through-managed-settings), los conectores de claude.ai que Claude Code [obtiene por sí mismo](#how-connectors-reach-claude-code) y los servidores integrados que están activados de forma predeterminada. Claude Code no se conecta a un servidor que incluyas aquí. Cuando desactivas un conector de claude.ai con el interruptor por proyecto de `/mcp` descrito en [Desactivar conectores de claude.ai](#disable-claude-ai-connectors), Claude Code lo escribe en esta lista con su nombre visible, por ejemplo `claude.ai Slack`.
336* `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í.336* `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 incluyes aquí.
337 337
338Claude 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.338Claude Code consulta exactamente una de las dos listas para cada servidor, así 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.
339 339
340`disabledMcpServers` y `enabledMcpServers` no están relacionados con [`enabledMcpjsonServers`](https://code.claude.com/docs/es/settings-reference#enabledmcpjsonservers) y [`disabledMcpjsonServers`](https://code.claude.com/docs/es/settings-reference#disabledmcpjsonservers), que controlan la aprobación de servidores definidos en el archivo `.mcp.json` de un proyecto.340`disabledMcpServers` y `enabledMcpServers` no están relacionados con [`enabledMcpjsonServers`](https://code.claude.com/docs/es/settings-reference#enabledmcpjsonservers) ni con [`disabledMcpjsonServers`](https://code.claude.com/docs/es/settings-reference#disabledmcpjsonservers), que controlan la aprobación de los servidores definidos en el archivo `.mcp.json` de un proyecto.
341 341
342### Tiempos de ejecución del cliente MCP342### Runtimes de cliente MCP
343 343
344Claude 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](https://ts.sdk.modelcontextprotocol.io/v2/), 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.344Claude Code se conecta a los servidores MCP mediante uno de dos runtimes de cliente. El runtime v1 está construido sobre el MCP TypeScript SDK 1.x. El runtime v2 es el mismo código sobre el [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/), que agrega la revisión 2026-07-28 del protocolo MCP. El resto de esta página se aplica a ambos runtimes, excepto donde una sección nombra el runtime v2.
345 345
346Claude Code elige un tiempo de ejecución cada vez que lo inicias y lo mantiene hasta que sales. En sesiones donde [obtiene feature flags](https://code.claude.com/docs/es/env-vars.md#features-that-need-feature-flag-fetching), utiliza el tiempo de ejecución v2 en Claude Code v2.1.232 o posterior.346Claude Code elige un runtime cada vez que lo inicias y lo mantiene hasta que sales. En las sesiones en las que [obtiene feature flags](https://code.claude.com/docs/es/env-vars.md#features-that-need-feature-flag-fetching), usa el runtime v2 en Claude Code v2.1.232 o posterior.
347 347
348En 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:348En las sesiones en las que no obtiene feature flags, Claude Code usa el runtime v2 de forma predeterminada en Claude Code v2.1.274 o posterior:
349 349
350* 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`](https://code.claude.com/docs/es/env-vars)350* Sesiones en Amazon Bedrock, Claude Platform on AWS, Agent Platform de Google Cloud o Microsoft Foundry, a menos que una plataforma host que integre Claude Code establezca [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/es/env-vars)
351* Sesiones iniciadas a través de un [gateway de aplicaciones de Claude](https://code.claude.com/docs/es/claude-apps-gateway)351* Sesiones iniciadas a través de un [gateway de aplicaciones de Claude](https://code.claude.com/docs/es/claude-apps-gateway)
352* Sesiones donde desactivas la telemetría o la obtención de feature flags, por ejemplo con `DISABLE_TELEMETRY`352* Sesiones en las que desactivas la telemetría o la obtención de feature flags, por ejemplo con `DISABLE_TELEMETRY`
353 353
354En v2, Claude Code también:354En v2, Claude Code además:
355 355
356* 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](https://code.claude.com/docs/es/remote-control.md). Claude Code se conecta a todos los demás servidores como lo hace v1.356* Pregunta a los servidores HTTP, stdio y de conectores de claude.ai si admiten la revisión más reciente y la usa con los que sí la admiten. Eso incluye los conectores de las sesiones en la nube y de [Remote Control](https://code.claude.com/docs/es/remote-control.md). Claude Code se conecta a cualquier otro servidor como lo hace v1.
357* Recibe notificaciones `list_changed` de servidores en la revisión más nueva a través de una [secuencia que mantiene abierta](#notification-streams-on-the-v2-runtime).357* Recibe notificaciones `list_changed` de los servidores con la revisión más reciente a través de un [flujo que mantiene abierto](#notification-streams-on-the-v2-runtime).
358* No registra un servidor de [canal](#push-messages-with-channels) que se conecta en la revisión más nueva, porque esa revisión no puede transportar mensajes de canal.358* No registra un servidor de [canal](#push-messages-with-channels) que se conecta con la revisión más reciente, porque esa revisión no puede transportar mensajes de canal.
359* Hace fallar un [inicio de sesión OAuth de MCP](#authenticate-with-remote-mcp-servers) cuya respuesta de autorización nombra un emisor inesperado.359* Hace fallar un [inicio de sesión de MCP OAuth](#authenticate-with-remote-mcp-servers) cuya respuesta de autorización nombra un emisor inesperado.
360* Envía credenciales de [OAuth de MCP](#authenticate-with-remote-mcp-servers) 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](https://code.claude.com/docs/es/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint).360* Envía las credenciales de [MCP OAuth](#authenticate-with-remote-mcp-servers) solo a un endpoint de token servido por 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 de tu red local. Consulta [Refusing to send credentials to non-https token endpoint](https://code.claude.com/docs/es/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint).
361 361
362Anthropic puede mantener un servidor específico en el protocolo anterior, o fuera de ese stream, con un feature flag que Claude Code obtiene. Para elegir el runtime tú mismo, establece [`MCP_SDK_GENERATION`](https://code.claude.com/docs/es/env-vars) en `v1` o `v2`.362Anthropic puede mantener un servidor específico en el protocolo anterior, o fuera de ese flujo, con un feature flag que Claude Code obtiene. Para elegir el runtime tú mismo, establece [`MCP_SDK_GENERATION`](https://code.claude.com/docs/es/env-vars) en `v1` o `v2`.
363 363
364Para decidir si Claude Code pregunta a los servidores por la revisión más reciente, establece [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/es/env-vars) en `auto` o `legacy`. Con esa variable sin establecer, Claude Code puede dejar de preguntar a un servidor stdio durante 7 días, por ejemplo después de que el servidor termina al preguntarle. Para que se le pregunte antes a un servidor actualizado, establece `auto`.364Para decidir si Claude Code pregunta a los servidores por la revisión más reciente, establece [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/es/env-vars) en `auto` o `legacy`. Con esa variable sin establecer, Claude Code puede omitir la pregunta a un servidor stdio durante 7 días, por ejemplo después de que el servidor sale al recibir la pregunta. Para que se le pregunte antes a un servidor actualizado, establece `auto`.
365 365
366### Actualizaciones dinámicas de herramientas366### Actualizaciones dinámicas de herramientas
367 367
368Un servidor MCP puede cambiar las herramientas, prompts o recursos que ofrece mientras está conectado y enviar una notificación `list_changed`. Cuando llega una:368Un servidor MCP puede cambiar las herramientas, prompts o recursos que ofrece mientras está conectado y enviar una notificación `list_changed`. Cuando llega una:
369 369
370* **En una sesión interactiva de terminal**, Claude Code obtiene la lista actualizada de ese servidor, por lo que no necesitas reconectarlo.370* **En una sesión interactiva de la terminal**, Claude Code obtiene la lista actualizada de ese servidor, así que no necesitas volver a conectarlo.
371* **En [modo no interactivo](https://code.claude.com/docs/es/headless.md) con el flag `-p` y en el [Agent SDK](https://code.claude.com/docs/es/agent-sdk/overview.md)**, Claude Code actualiza solo la lista de herramientas con estas notificaciones.371* **En [modo no interactivo](https://code.claude.com/docs/es/headless.md) con el flag `-p` y en el [Agent SDK](https://code.claude.com/docs/es/agent-sdk/overview.md)**, Claude Code actualiza solo la lista de herramientas con estas notificaciones.
372 372
373Si 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.373Si una solicitud de actualización falla, Claude Code conserva las herramientas, prompts y recursos descubiertos previamente del servidor hasta que una actualización posterior tenga éxito.
374 374
375#### Secuencias de notificación en el tiempo de ejecución v2375#### Flujos de notificaciones en el runtime v2
376 376
377En el [tiempo de ejecución v2](#mcp-client-runtimes), 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:377En el [runtime v2](#mcp-client-runtimes), Claude Code recibe notificaciones `list_changed` de un servidor con la revisión más reciente del protocolo a través de un flujo que mantiene abierto. Cuando el flujo se cierra, Claude Code lo vuelve a abrir, con dos límites:
378 378
379* **La secuencia se cierra nuevamente dentro de 10 segundos**: Claude Code la reabre hasta tres veces y luego se detiene para esa conexión.379* **El flujo se vuelve a cerrar en menos de 10 segundos**: Claude Code lo reabre hasta tres veces y luego deja de hacerlo para esa conexión.
380* **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.380* **El flujo permanece abierto más de 10 segundos y luego se cierra**, como suele ocurrir con los flujos hacia hosts serverless: después de cinco reaperturas en una hora, Claude Code espera unas seis horas antes de la siguiente.
381 381
382Hasta 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`.382Hasta que el flujo se reabre, conservas las últimas herramientas, prompts y recursos obtenidos del servidor. Para recibir sus cambios antes, vuelve a conectar el servidor desde `/mcp`.
383 383
384### Reconexión automática384### Reconexión automática
385 385
386Claude 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](#stdio-servers-that-exit-or-fail-to-start).386Claude Code vuelve a conectar un servidor remoto que se cae a mitad de la 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 salen o no logran iniciarse](#stdio-servers-that-exit-or-fail-to-start).
387 387
388#### Caídas a mitad de sesión de un servidor remoto388#### Caídas de un servidor remoto a mitad de la sesión
389 389
390Claude 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:390Claude Code primero intenta volver a conectar un servidor remoto caído hasta cinco veces con retroceso exponencial, comenzando con un retraso de un segundo y duplicándolo cada vez:
391 391
392* **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`.392* **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 lo marca como fallido, ves una notificación `MCP server "<name>" disconnected · open /mcp to reconnect`. Puedes reintentar manualmente desde `/mcp`.
393* **En ejecuciones de [`claude -p`](https://code.claude.com/docs/es/headless) y sesiones del [Agent SDK](https://code.claude.com/docs/es/agent-sdk/overview.md)**: 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:393* **En ejecuciones de [`claude -p`](https://code.claude.com/docs/es/headless) y sesiones del [Agent SDK](https://code.claude.com/docs/es/agent-sdk/overview.md)**: Claude Code hace los mismos cinco intentos, sin un panel `/mcp` donde mostrarlos. Si los cinco fallan, la ejecución continúa sin las herramientas del servidor:
394 * **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](https://code.claude.com/docs/es/agent-sdk/mcp.md#error-handling) `failed`, y tu código puede [reconectar el servidor](https://code.claude.com/docs/es/agent-sdk/mcp.md#error-handling). Para reconectarlo en `claude -p`, vuelve a iniciar la ejecución.394 * **Después de un error transitorio, como una respuesta 5xx o un tiempo de espera agotado**: Claude Code sigue reintentando un servidor HTTP o SSE en segundo plano. Los reintentos duran hasta una media hora aproximadamente, y las herramientas del servidor vuelven a estar disponibles cuando uno se conecta. Hasta entonces, una sesión del Agent SDK informa el [estado](https://code.claude.com/docs/es/agent-sdk/mcp.md#error-handling) `failed`, y tu código puede [volver a conectar el servidor](https://code.claude.com/docs/es/agent-sdk/mcp.md#error-handling). Para volver a conectarlo en `claude -p`, inicia la ejecución de nuevo.
395 * **Cuando el servidor [necesita que vuelvas a iniciar sesión](#authenticate-with-remote-mcp-servers)**: 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>`](#authenticate-from-the-command-line) en tu shell. Luego vuelve a iniciar la ejecución o, en una sesión del Agent SDK, [reconecta el servidor](https://code.claude.com/docs/es/agent-sdk/mcp.md#error-handling) en su lugar.395 * **Cuando el servidor [necesita que vuelvas a iniciar sesión](#authenticate-with-remote-mcp-servers)**: 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>`](#authenticate-from-the-command-line) en tu shell. Luego inicia la ejecución de nuevo o, en una sesión del Agent SDK, [vuelve a conectar el servidor](https://code.claude.com/docs/es/agent-sdk/mcp.md#error-handling) en su lugar.
396 396
397#### Conexiones iniciales fallidas397#### Primeras conexiones fallidas
398 398
399Cuando 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.399Cuando la primera conexión de un servidor HTTP o SSE falla con un error transitorio, como una respuesta 5xx, una conexión rechazada o un tiempo de espera agotado, Claude Code reintenta hasta tres veces. Si la conexión sigue fallando, Claude Code marca el servidor como fallido.
400 400
401Esos reintentos no se aplican en estos casos:401Esos reintentos no se aplican en estos casos:
402 402
403* La primera conexión de un servidor stdio. Para intentarla de nuevo, consulta [Servidores stdio que terminan o no logran iniciarse](#stdio-servers-that-exit-or-fail-to-start)403* La primera conexión de un servidor stdio. Para intentarlo de nuevo, consulta [Servidores stdio que salen o no logran iniciarse](#stdio-servers-that-exit-or-fail-to-start)
404* 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`404* La primera conexión de un servidor WebSocket. Para intentarlo de nuevo en una sesión interactiva de la terminal, selecciona **Reconnect** en el menú del servidor en `/mcp`
405* Un error de autenticación o de recurso no encontrado, porque requiere un cambio de configuración para resolverse. Cuando un [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 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 nueva405* Un error de autenticación o de recurso no encontrado, porque requiere un cambio de configuración para resolverse. Cuando un [`headersHelper`](#use-dynamic-headers-for-custom-authentication) es la única fuente del encabezado `Authorization` del servidor, Claude Code reintenta de todos modos un error de autenticación, porque vuelve a ejecutar el helper en cada intento y puede obtener una credencial nueva
406 406
407#### Servidores stdio que terminan o no logran iniciarse407#### Servidores stdio que salen o no logran iniciarse
408 408
409Para 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.409Para iniciar de nuevo 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.
410 410
411| Cómo ejecutas Claude Code | El proceso del servidor termina a mitad de sesión | La primera conexión del servidor falla |411| Cómo ejecutas Claude Code | El proceso del servidor sale a mitad de la sesión | La primera conexión del servidor falla |
412| - | - | - |412| - | - | - |
413| Sesión interactiva | Claude Code marca el servidor como fallido. Para iniciarlo de nuevo, selecciona **Reconnect** en el menú del servidor en `/mcp` | Claude Code marca el servidor como fallido. Para iniciarlo de nuevo, selecciona **Reconnect** en el menú del servidor en `/mcp` |413| Sesión interactiva | Claude Code marca el servidor como fallido. Para iniciarlo de nuevo, selecciona **Reconnect** en el menú del servidor en `/mcp` | Claude Code marca el servidor como fallido. Para iniciarlo de nuevo, selecciona **Reconnect** en el menú del servidor en `/mcp` |
414| Ejecución de `claude -p` | Claude Code vuelve a iniciar el servidor la próxima vez que Claude llama a una de las herramientas del servidor, y la llamada se ejecuta en cuanto el servidor se conecta | La ejecución continúa sin las herramientas del servidor. Para que Claude Code vuelva a intentar la conexión, vuelve a iniciar la ejecución. Cuando un plugin proporciona el servidor, las nuevas ejecuciones omiten la conexión durante 15 minutos después de una falla, así que espera ese tiempo primero o [reintenta antes](https://code.claude.com/docs/es/errors.md#skipping-connection-recent-failure-cached) |414| Ejecución de `claude -p` | Claude Code inicia el servidor de nuevo la próxima vez que Claude llama a una de sus herramientas, y la llamada se ejecuta en cuanto el servidor se conecta | La ejecución continúa sin las herramientas del servidor. Para que Claude Code intente la conexión de nuevo, inicia la ejecución otra vez. Cuando un plugin proporciona el servidor, las nuevas ejecuciones omiten la conexión durante 15 minutos después de un fallo, así que espera ese tiempo primero o [reintenta antes](https://code.claude.com/docs/es/errors.md#skipping-connection-recent-failure-cached) |
415| Sesión del Agent SDK | Claude Code vuelve a iniciar el servidor la próxima vez que Claude llama a una de las herramientas del servidor, y la llamada se ejecuta en cuanto el servidor se conecta | La sesión continúa sin las herramientas del servidor. Tu código puede [reconectar el servidor](https://code.claude.com/docs/es/agent-sdk/mcp.md#error-handling) |415| Sesión del Agent SDK | Claude Code inicia el servidor de nuevo la próxima vez que Claude llama a una de sus herramientas, y la llamada se ejecuta en cuanto el servidor se conecta | La sesión continúa sin las herramientas del servidor. Tu código puede [volver a conectar el servidor](https://code.claude.com/docs/es/agent-sdk/mcp.md#error-handling) |
416 416
417#### Solicitudes de descubrimiento fallidas417#### Solicitudes de descubrimiento fallidas
418 418
419Despué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.419Despué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 breve 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 agotó.
420 420
421#### Reintentar tú mismo los servidores fallidos421#### Reintentar tú mismo los servidores fallidos
422 422
423Para 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`.423Para 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 la terminal. Esto requiere Claude Code v2.1.284 o posterior. Las versiones anteriores imprimen `MCP server "all" not found`.
424 424
425#### Cómo Claude se entera de que un servidor falló425#### Cómo se entera Claude de que un servidor falló
426 426
427Que Claude Code le informe a Claude sobre un servidor configurado que no pudo conectarse depende de la [búsqueda de herramientas](#scale-with-mcp-tool-search), que está activada de forma predeterminada:427Que Claude Code le informe a Claude sobre un servidor configurado que no logró conectarse depende de la [búsqueda de herramientas](#scale-with-mcp-tool-search), que está activada de forma predeterminada:
428 428
429* 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.429* Con búsqueda de herramientas, Claude Code le dice a Claude qué servidor falló y su error de conexión, para que Claude informe el fallo de conexión en su respuesta. Claude Code incluye la misma información en los resultados de `ToolSearch` que no encuentran ninguna herramienta coincidente.
430* En cualquier [configuración sin búsqueda de herramientas](#configure-tool-search), Claude Code no informa a Claude de las conexiones fallidas de servidores.430* En cualquier [configuración sin búsqueda de herramientas](#configure-tool-search), Claude Code no informa a Claude de las conexiones de servidor fallidas.
431 431
432### Enviar mensajes con canales432### Enviar mensajes con canales
433 433
434Un 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](https://code.claude.com/docs/es/channels.md) para usar un canal con soporte oficial, o [Channels reference](https://code.claude.com/docs/es/channels-reference.md) para crear el tuyo propio.434Un servidor MCP también puede enviar mensajes directamente a tu sesión para que Claude reaccione a eventos externos como resultados de CI, alertas de monitoreo o mensajes de chat. Para habilitarlo, tu servidor declara la capacidad `claude/channel` y tú lo habilitas con el flag `--channels` al iniciar. Consulta [Canales](https://code.claude.com/docs/es/channels.md) para usar un canal con soporte oficial, o la [Referencia de canales](https://code.claude.com/docs/es/channels-reference.md) para crear el tuyo.
435 435
436En el [tiempo de ejecución v2](#mcp-client-runtimes), 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.436En el [runtime v2](#mcp-client-runtimes), un servidor de canal que negocia la revisión 2026-07-28 del protocolo MCP no puede entregar mensajes de canal, así que Claude Code no lo registra como canal. Un servidor de canal que no admite esa revisión se conecta con el handshake anterior y se registra como antes.
437 437
438Claude 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`](https://code.claude.com/docs/es/env-vars) en `legacy`, lo que mantiene todos los servidores en él.438Claude Code pide esa revisión a los servidores stdio de forma predeterminada. Para mantener un servidor de canal stdio en el handshake anterior, establece [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/es/env-vars) en `legacy`, lo que mantiene a todos los servidores en él.
439 439
440> [!TIP]440> [!TIP]
441>441>
443>443>
444> * Usa el flag `-s` o `--scope` para especificar dónde se almacena la configuración:444> * Usa el flag `-s` o `--scope` para especificar dónde se almacena la configuración:
445> * `local` (predeterminado): disponible solo para ti en el proyecto actual445> * `local` (predeterminado): disponible solo para ti en el proyecto actual
446> * `project`: compartido con todos en el proyecto a través del archivo `.mcp.json`446> * `project`: compartido con todos en el proyecto mediante el archivo `.mcp.json`
447> * `user`: disponible para ti en todos los proyectos447> * `user`: disponible para ti en todos los proyectos
448> * Establece variables de entorno con los flags `-e` o `--env` (por ejemplo, `-e KEY=value`)448> * Establece variables de entorno con los flags `-e` o `--env` (por ejemplo, `-e KEY=value`)
449> * Los flags `--transport` y `--header` también aceptan las formas cortas `-t` y `-H`449> * Los flags `--transport` y `--header` también aceptan las formas cortas `-t` y `-H`
450> * 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)450> * Configura el tiempo de espera de inicio del servidor MCP con la variable de entorno `MCP_TIMEOUT` (por ejemplo, `MCP_TIMEOUT=10000 claude` establece un tiempo de espera de 10 segundos)
451> * 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 servidor451> * Establece un tiempo de espera de ejecución de herramientas por servidor agregando un campo `timeout` en milisegundos a la entrada de `.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
452> * 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](#mcp-output-limits-and-warnings)452> * Claude Code muestra una advertencia cuando la salida de una herramienta MCP supera los 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 correctos de más de 50,000 caracteres se guardan en un archivo independientemente de esta variable. Consulta [Límites y advertencias de salida de MCP](#mcp-output-limits-and-warnings)
453> * Usa `/mcp` para autenticarte con servidores remotos que requieren autenticación OAuth 2.0453> * Usa `/mcp` para autenticarte con servidores remotos que requieren autenticación OAuth 2.0
454 454
455### Límites de tiempo en las llamadas a herramientas MCP455### Límites de tiempo en las llamadas a herramientas MCP
456 456
457Para limitar cuánto tiempo puede durar una llamada a herramienta MCP:457Para limitar cuánto tiempo puede ejecutarse una llamada a herramienta MCP:
458 458
459* **Por servidor**: agrega un campo `timeout` en milisegundos a la entrada de configuración de ese servidor459* **Por servidor**: agrega un campo `timeout` en milisegundos a la entrada de configuración de ese servidor
460* **Para todos los servidores**: establece [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/es/env-vars)460* **Para todos los servidores**: establece [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/es/env-vars)
461 461
462El `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](https://code.claude.com/docs/es/mcp.md#use-mcp-servers-from-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.462El `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 inferiores a 1000 se ignoran y se recurre a `MCP_TOOL_TIMEOUT`, o a su valor predeterminado de unas 28 horas cuando esa variable no está establecida. Para un servidor HTTP, SSE o de [conector de claude.ai](https://code.claude.com/docs/es/mcp.md#use-mcp-servers-from-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 inferior a 60 segundos no acorta el temporizador. Los servidores stdio y WebSocket no tienen temporizador por solicitud.
463 463
464Un `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.464Un `timeout` por servidor de al menos 1000 también actúa como mínimo del tiempo de espera por inactividad descrito a continuación: Claude Code nunca aborta las llamadas a herramientas de ese servidor por inactividad antes del `timeout` por servidor.
465 465
466Una 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](#use-mcp-servers-from-claude-ai), y de 30 minutos para servidores stdio.466Una llamada a herramienta a un servidor MCP que no envía ninguna respuesta ni notificación de progreso durante la ventana de inactividad se aborta con un error en lugar de esperar al límite de tiempo real. El tiempo de espera por inactividad se aplica a todos los tipos de servidor excepto los servidores de IDE y los servidores en proceso del SDK. La ventana de inactividad es de cinco minutos de forma predeterminada para los servidores HTTP, SSE, WebSocket y de [conectores de claude.ai](#use-mcp-servers-from-claude-ai), y de 30 minutos para los servidores stdio.
467 467
468Establece la variable de entorno [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/es/env-vars) en milisegundos para cambiar la ventana de inactividad, o establécela en `0` para deshabilitar la verificación.468Establece la variable de entorno [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/es/env-vars) en milisegundos para cambiar la ventana de inactividad, o establécela en `0` para desactivar la comprobación.
469 469
470Estos 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](#automatic-backgrounding-of-long-tool-calls).470Estos tiempos de espera limitan cuánto 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 primero a una tarea en segundo plano. Consulta [Paso automático a segundo plano de llamadas a herramientas largas](#automatic-backgrounding-of-long-tool-calls).
471 471
472### Ejecución automática en segundo plano de llamadas a herramientas largas472### Paso automático a segundo plano de llamadas a herramientas largas
473 473
474Si la vista de detalle de una llamada en segundo plano en [`/tasks`](https://code.claude.com/docs/es/commands#all-commands) muestra `runs on the server; survives exiting this session`, consulta [Tareas MCP que se ejecutan en el servidor](#mcp-tasks-that-run-on-the-server).474Si la vista de detalle de una llamada en segundo plano en [`/tasks`](https://code.claude.com/docs/es/commands#all-commands) muestra `runs on the server; survives exiting this session`, consulta [Tareas MCP que se ejecutan en el servidor](#mcp-tasks-that-run-on-the-server).
475 475
476Una 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.476Una llamada a herramienta MCP en la conversación principal que sigue en ejecución 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 de inmediato y sigue trabajando, y el resultado llega como una notificación de tarea cuando la llamada termina.
477 477
478La tarea aparece en [`/tasks`](https://code.claude.com/docs/es/commands#all-commands), 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.478La tarea aparece en [`/tasks`](https://code.claude.com/docs/es/commands#all-commands), donde también puedes detenerla, y no sobrevive a la salida de la sesión. La entrada de la tarea muestra el último progreso que informó el servidor. 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.
479 479
480Los 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`](https://code.claude.com/docs/es/env-vars), y el tiempo de espera de inactividad establecido por [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/es/env-vars).480Los límites por llamada siguen aplicándose mientras la llamada se ejecuta en segundo plano: el límite de tiempo real establecido por el `timeout` por servidor o por [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/es/env-vars), y el tiempo de espera por inactividad establecido por [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/es/env-vars).
481 481
482Para cambiar o desactivar el paso automático a segundo plano:482Para cambiar o desactivar el paso automático a segundo plano:
483 483
484* Establece la variable de entorno [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/es/env-vars) 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](#make-claude-wait-for-the-result-of-an-mcp-task) en una sesión interactiva484* Establece la variable de entorno [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/es/env-vars) 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 a las tareas MCP](#make-claude-wait-for-the-result-of-an-mcp-task) en una sesión interactiva
485* Establece [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/es/env-vars) en `1` para desactivar el paso automático a segundo plano y los [comandos en segundo plano](https://code.claude.com/docs/es/tools-reference.md#background-commands)485* Establece [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/es/env-vars) en `1` para desactivar el paso automático a segundo plano y los [comandos en segundo plano](https://code.claude.com/docs/es/tools-reference.md#background-commands)
486 486
487Algunas llamadas nunca pasan a segundo plano:487Algunas llamadas nunca pasan a segundo plano:
488 488
489* Llamadas de [subagentes](https://code.claude.com/docs/es/sub-agents.md); Claude Code solo pasa a segundo plano las llamadas de la conversación principal489* Las llamadas de [subagentes](https://code.claude.com/docs/es/sub-agents.md); Claude Code pasa a segundo plano solo las llamadas de la conversación principal
490* Llamadas a servidores IDE490* Las llamadas a servidores de IDE
491* Llamadas en [modo no interactivo](https://code.claude.com/docs/es/headless.md), a menos que `CLAUDE_AUTO_BACKGROUND_TASKS` esté establecido en `1`, ya que una ejecución única puede terminar antes de que llegue el resultado491* Las llamadas en [modo no interactivo](https://code.claude.com/docs/es/headless.md), 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
492 492
493Una llamada que espera en un [diálogo de elicitación](#respond-to-mcp-elicitation-requests) 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.493Una llamada que espera un [diálogo de elicitación](#respond-to-mcp-elicitation-requests) abierto no pasa a segundo plano mientras el diálogo está abierto; el servidor está bloqueado esperando tu entrada, no es lento, así que Claude Code pospone el paso hasta que el diálogo se cierra.
494 494
495### Tareas MCP que se ejecutan en el servidor495### Tareas MCP que se ejecutan en el servidor
496 496
497Una 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](https://modelcontextprotocol.io/extensions/tasks/overview). 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](#make-claude-wait-for-the-result-of-an-mcp-task). Cuando el trabajo termina, la transcripción lo indica y Claude recibe el resultado. Pídeselo a Claude.497Una 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](https://modelcontextprotocol.io/extensions/tasks/overview). 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](#make-claude-wait-for-the-result-of-an-mcp-task). Cuando el trabajo termina, la transcripción lo indica y Claude recibe el resultado. Pídeselo a Claude.
498 498
499Mientras 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](#exit-clear-or-resume-while-an-mcp-task-runs).499Mientras tanto, el pie muestra un recuento como `1 MCP task`, y Claude Code sigue la tarea comprobando 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](#exit-clear-or-resume-while-an-mcp-task-runs).
500 500
501> [!NOTE]501> [!NOTE]
502>502>
503> 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](#requirements-for-mcp-tasks) enumera las sesiones y los servidores que las obtienen.503> 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](#requirements-for-mcp-tasks) lista las sesiones y los servidores que las obtienen.
504 504
505#### Detener una tarea MCP u obtener su resultado505#### Detener una tarea MCP u obtener su resultado
506 506
507Para detener una tarea en ejecución, selecciónala en [`/tasks`](https://code.claude.com/docs/es/commands#all-commands) 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.507Para detener una tarea en ejecución, selecciónala en [`/tasks`](https://code.claude.com/docs/es/commands#all-commands) 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 podría terminarla de todos modos. Vuelve a conectar primero desde `/mcp` un servidor desconectado; de lo contrario, 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.
508 508
509Cuando la tarea termina, aparece en la transcripción una línea como esta:509Cuando la tarea termina, aparece en la transcripción una línea como esta:
510 510
512MCP task <server task id> (<server>/<tool>) completed.512MCP task <server task id> (<server>/<tool>) completed.
513```513```
514 514
515El 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.515El resultado va a Claude, no a la transcripción, así que pídeselo a Claude. Si Claude está inactivo cuando llega el resultado, Claude empieza a trabajar con él sin que se lo pidas.
516 516
517#### Responder a una pregunta de una tarea MCP517#### Responder a una pregunta de una tarea MCP
518 518
524 524
525Una 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`.525Una 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`.
526 526
527| Situación | Qué le ocurre a la tarea | Qué puedes hacer |527| Situación | Qué le pasa a la tarea | Qué puedes hacer |
528| - | - | - |528| - | - | - |
529| Ejecutas `/clear` o `/branch`, o usas `/resume` con otra sesión | Mientras Claude Code sigue abierto, el resultado llega a tu conversación actual | Después de salir, usa `claude --resume` con la sesión en la que empezó la tarea |529| Ejecutas `/clear` o `/branch`, o usas `/resume` con otra sesión | Mientras Claude Code siga abierto, el resultado llega a tu conversación actual | Después de salir, usa `claude --resume` con la sesión en la que empezó la tarea |
530| Sales de Claude Code | Ninguna opción de salida cancela la tarea de un servidor remoto, aunque el diálogo de salida la incluya bajo `The following will stop when you exit:` | Detenla primero en `/tasks`, o reanuda la misma sesión más tarde |530| Sales de Claude Code | Ninguna opción de salida cancela la tarea de un servidor remoto, incluso cuando el diálogo de salida la lista bajo `The following will stop when you exit:` | Detenla primero en `/tasks`, o reanuda la misma sesión más tarde |
531| Vuelves a la sesión de la tarea de forma interactiva: `claude --resume`, `claude --continue` o `/resume` | En cuanto el servidor se conecta, Claude Code vuelve a seguir la tarea, y Claude recibe el resultado si terminó mientras tanto y el servidor todavía lo conoce | Mantén sin cambios el nombre y la configuración de conexión del servidor |531| Vuelves a la sesión de la tarea de forma interactiva: `claude --resume`, `claude --continue` o `/resume` | En cuanto el servidor se conecta, Claude Code vuelve a seguir la tarea, y Claude recibe el resultado si terminó mientras tanto y el servidor todavía lo conoce | Mantén sin cambios el nombre y la configuración de conexión del servidor |
532| Reanudas la sesión de la tarea con `--resume` o `--continue` en una ejecución única `claude -p "<prompt>"` | Esa ejecución no sigue la tarea | Reanuda de forma interactiva, o con `--input-format stream-json` |532| Reanudas la sesión de la tarea con `--resume` o `--continue` en una ejecución única `claude -p "<prompt>"` | Esa ejecución no sigue la tarea | Reanuda de forma interactiva, o con `--input-format stream-json` |
533| Inicias una sesión nueva o usas `--fork-session` | La nueva sesión no sigue la tarea | Reanuda la sesión que la inició |533| Inicias una sesión nueva o usas `--fork-session` | La sesión nueva no sigue la tarea | Reanuda la sesión que la inició |
534 534
535#### Qué necesita una llamada para convertirse en una tarea MCP535#### Qué necesita una llamada para convertirse en una tarea MCP
536 536
538 538
539* El servidor admite tareas539* El servidor admite tareas
540* El servidor es un servidor HTTP, stdio o de conector de claude.ai conectado con la [revisión 2026-07-28 del protocolo](#mcp-client-runtimes). Establecer [`MCP_SDK_GENERATION=v1` o `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/es/env-vars) lo descarta540* El servidor es un servidor HTTP, stdio o de conector de claude.ai conectado con la [revisión 2026-07-28 del protocolo](#mcp-client-runtimes). Establecer [`MCP_SDK_GENERATION=v1` o `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/es/env-vars) lo descarta
541* La sesión [obtiene feature flags](https://code.claude.com/docs/es/env-vars.md#features-that-need-feature-flag-fetching), así que no en un proveedor externo como Amazon Bedrock, ni con la telemetría o la obtención de flags desactivadas541* La sesión [obtiene feature flags](https://code.claude.com/docs/es/env-vars.md#features-that-need-feature-flag-fetching), por lo que no está en un proveedor externo como Amazon Bedrock ni tiene desactivadas la telemetría o la obtención de flags
542* 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](https://code.claude.com/docs/es/agent-sdk/overview.md) y las ejecuciones de [GitHub Actions](https://code.claude.com/docs/es/github-actions.md). Otras superficies, como la [extensión de VS Code](https://code.claude.com/docs/es/vs-code.md) y la [aplicación de escritorio](https://code.claude.com/docs/es/desktop.md), no tienen tareas MCP542* Anthropic activó las tareas MCP para tu tipo de sesión. En v2.1.304 o posterior eso cubre las sesiones de la CLI en la terminal, las sesiones del [Agent SDK](https://code.claude.com/docs/es/agent-sdk/overview.md) y las ejecuciones de [GitHub Actions](https://code.claude.com/docs/es/github-actions.md). Otras superficies, como la [extensión de VS Code](https://code.claude.com/docs/es/vs-code.md) y la [aplicación de escritorio](https://code.claude.com/docs/es/desktop.md), no tienen tareas MCP
543* La llamada proviene de la conversación principal, no de un [subagente](https://code.claude.com/docs/es/sub-agents.md)543* La llamada proviene de la conversación principal, no de un [subagente](https://code.claude.com/docs/es/sub-agents.md)
544* O bien la sesión es interactiva, o bien una sesión del [Agent SDK](https://code.claude.com/docs/es/agent-sdk/overview.md) o una ejecución de `claude -p` que lee `--input-format stream-json` tiene:544* O bien la sesión es interactiva, o bien una sesión del [Agent SDK](https://code.claude.com/docs/es/agent-sdk/overview.md) o una ejecución de `claude -p` que lee `--input-format stream-json` tiene:
545 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/es/env-vars) en `1`545 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/es/env-vars) en `1`
546 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` distinto de `1`546 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` distinto de `1`
547 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` distinto de `0`547 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` distinto de `0`
548 548
549Cualquier otra llamada es una llamada a herramienta normal, y [Paso automático a segundo plano de las llamadas a herramientas largas](#automatic-backgrounding-of-long-tool-calls) indica cuáles de ellas pasan a segundo plano.549Cualquier otra llamada es una llamada a herramienta simple, y [Paso automático a segundo plano de llamadas a herramientas largas](#automatic-backgrounding-of-long-tool-calls) indica cuáles de ellas pasan a segundo plano.
550 550
551Manté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](https://code.claude.com/docs/es/headless.md#mcp-work-when-a-non-interactive-run-ends) después de que se cierra la entrada. Una ejecución única `claude -p "<prompt>"` no obtiene tareas MCP.551Manté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](https://code.claude.com/docs/es/headless.md#mcp-work-when-a-non-interactive-run-ends) después de que se cierra la entrada. Una ejecución única `claude -p "<prompt>"` no obtiene tareas MCP.
552 552
553#### Mensajes de estado de una tarea MCP553#### Mensajes de estado en una tarea MCP
554 554
555Estos 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.555Estos mensajes, en la entrada de una tarea en `/tasks` o en su línea de cierre de la transcripción, significan que Claude Code no puede comunicarse con el servidor o con la tarea. Mientras uno se muestra en `/tasks`, el trabajo puede seguir ejecutándose: 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.
556 556
557| Mensaje | Qué está ocurriendo | Qué puedes hacer |557| Mensaje | Qué está pasando | Qué puedes hacer |
558| - | - | - |558| - | - | - |
559| `reconnecting…` | El servidor no ha respondido desde una reanudación, o las comprobaciones de estado no obtienen respuesta | Si persiste, vuelve a conectar desde `/mcp` |559| `reconnecting…` | El servidor no ha respondido desde una reanudación, o las comprobaciones de estado no reciben respuesta | Si persiste, vuelve a conectar desde `/mcp` |
560| `needs a sign-in to <server>` | El servidor rechazó una comprobación de estado | Inicia sesión desde `/mcp` |560| `needs a sign-in to <server>` | El servidor rechazó una comprobación de estado | Inicia sesión desde `/mcp` |
561| `status requests come back with errors; retrying…` | El servidor, o un proxy delante de él, responde a las comprobaciones de estado con errores | Espera mientras Claude Code reintenta |561| `status requests come back with errors; retrying…` | El servidor, o un proxy delante de él, responde a las comprobaciones de estado con errores | Espera mientras Claude Code reintenta |
562| `server '<name>' did not reconnect within 300s` | Ninguna comprobación respondida durante cinco minutos, por ejemplo con la conexión caída o el servidor desactivado | Vuelve a conectar desde `/mcp` |562| `server '<name>' did not reconnect within 300s` | Ninguna comprobación respondida durante cinco minutos, por ejemplo con la conexión caída o el servidor desactivado | Vuelve a conectar desde `/mcp` |
563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | Después de cinco minutos, el servidor sigue pidiendo un inicio de sesión | Inicia sesión desde `/mcp` |563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | Después de cinco minutos, el servidor todavía pide un inicio de sesión | Inicia sesión desde `/mcp` |
564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | Cinco minutos de respuestas con error | Revisa la salud o los registros del propio servidor |564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | Cinco minutos de respuestas con error | Revisa el estado o los registros del propio servidor |
565| `server '<name>' is not configured in this session; the task may still be running on it` | La sesión no tiene ningún servidor con ese nombre, por ejemplo porque se eliminó, se renombró o se dejó fuera de `--mcp-config`, o porque un conector de claude.ai todavía se está cargando | Restaura el servidor con el mismo nombre y luego vuelve a reanudar la sesión. Para un conector que se está cargando, nada: Claude Code sigue la tarea en cuanto aparece |565| `server '<name>' is not configured in this session; the task may still be running on it` | La sesión no tiene ningún servidor con ese nombre, por ejemplo porque se eliminó, se le cambió el nombre o se omitió de `--mcp-config`, o un conector de claude.ai todavía se está cargando | Restaura el servidor con el mismo nombre y luego reanuda la sesión de nuevo. Para un conector que se está cargando, nada: Claude Code sigue la tarea en cuanto aparece |
566| Un mensaje que empieza con `server '<name>' was reconfigured to a different transport since this task was created` | Existe un servidor con ese nombre cuya configuración de conexión cambió desde que empezó la tarea, como su URL, command, args, env, headers o timeout | Restaura la configuración anterior y luego vuelve a reanudar la sesión |566| Un mensaje que empieza con `server '<name>' was reconfigured to a different transport since this task was created` | Existe un servidor con ese nombre cuya configuración de conexión cambió desde que empezó la tarea, como su URL, comando, args, env, headers o timeout | Restaura la configuración anterior y luego reanuda la sesión de nuevo |
567| `the server rejected this task's id; asking again…` | El servidor dice que no conoce el ID de la tarea. Claude Code sigue preguntando durante hasta cinco minutos | Espera: el mensaje desaparece si el servidor vuelve a reconocer el ID, o le sigue la línea `outcome unknown.` |567| `the server rejected this task's id; asking again…` | El servidor dice que no conoce el ID de la tarea. Claude Code sigue preguntando hasta cinco minutos | Espera: el mensaje desaparece si el servidor vuelve a reconocer el ID, o aparece a continuación la línea `outcome unknown.` |
568| Una línea de la transcripción que termina en `outcome unknown.`, en una de sus formas `expired on the server: outcome unknown.` | El servidor rechazó el ID o se negó con otro error permanente, y Claude Code dejó de seguir la tarea | Una segunda llamada puede repetir el trabajo. Antes de volver a llamar a la herramienta, averigua con el servidor qué se hizo, por ejemplo pidiéndole a Claude que use las demás herramientas del servidor |568| Una línea de la transcripción que termina en `outcome unknown.`, en una de sus formas `expired on the server: outcome unknown.` | El servidor rechazó el ID o se negó con otro error permanente, y Claude Code dejó de seguir la tarea | Una segunda llamada podría repetir el trabajo. Antes de volver a llamar a la herramienta, averigua con el servidor qué se hizo, por ejemplo pidiéndole a Claude que use las otras herramientas del servidor |
569 569
570#### Límites de tiempo en las tareas MCP570#### Límites de tiempo en las tareas MCP
571 571
576Para 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`](https://code.claude.com/docs/es/settings):576Para 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`](https://code.claude.com/docs/es/settings):
577 577
578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/es/env-vars) establecida en `0`**: Claude espera cada llamada a herramienta MCP hasta que la llamada termina578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/es/env-vars) establecida en `0`**: Claude espera cada llamada a herramienta MCP hasta que la llamada termina
579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/es/env-vars) establecida en `1`**: Claude espera el resultado de una tarea. Mientras el [paso automático a segundo plano](#automatic-backgrounding-of-long-tool-calls) 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ón579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/es/env-vars) establecida en `1`**: Claude espera el resultado de una tarea. Mientras el [paso automático a segundo plano](#automatic-backgrounding-of-long-tool-calls) 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 en segundo plano simple, no una tarea MCP. No sobrevive a la salida de la sesión
580 580
581Mientras Claude espera, presionar `Esc` o alcanzar el [límite de tiempo real o el tiempo de espera por inactividad](#time-limits-on-mcp-tasks) termina la llamada, y Claude Code le pide al servidor que cancele la tarea.581Mientras Claude espera, presionar `Esc` o alcanzar el [límite de tiempo real o el tiempo de espera por inactividad](#time-limits-on-mcp-tasks) termina la llamada, y Claude Code le pide al servidor que cancele la tarea.
582 582
583Si estableces `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` en `1` o inicias en [modo bare](https://code.claude.com/docs/es/headless.md#start-faster-with-bare-mode), 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:583Si estableces `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` en `1` o inicias en [modo bare](https://code.claude.com/docs/es/headless.md#start-faster-with-bare-mode), eso por sí solo no hace que Claude espere a las tareas MCP. Este ejemplo establece `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` en `0`, por lo que Claude espera cada llamada a herramienta MCP:
584 584
585```json settings.json theme={null}585```json settings.json theme={null}
586{586{
592 592
593### Tareas MCP para autores de servidores593### Tareas MCP para autores de servidores
594 594
595Si creas un servidor MCP, puedes responder a un `tools/call` de larga duración con una tarea. La [extensión de tareas de MCP](https://modelcontextprotocol.io/extensions/tasks/overview) define los mensajes que envías. En una conexión con la [revisión 2026-07-28 del protocolo](#mcp-client-runtimes), 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](#requirements-for-mcp-tasks) omite esa extensión.595Si creas un servidor MCP, puedes responder a un `tools/call` de larga duración con una tarea. La [extensión de tareas de MCP](https://modelcontextprotocol.io/extensions/tasks/overview) define los mensajes que envías. En una conexión con la [revisión 2026-07-28 del protocolo](#mcp-client-runtimes), 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 tarea](#requirements-for-mcp-tasks) omite esa extensión.
596 596
597#### Responder a la llamada con una tarea597#### Responder a la llamada con una tarea
598 598
599Responde con una tarea solo cuando la solicitud lleve la extensión; de lo contrario, la llamada falla con el error de herramienta `Unsupported result type 'task' for tools/call`. La llamada falla de la misma manera si tu respuesta no tiene `taskId` o no tiene un `status` válido. El objeto de la tarea es el `result` JSON-RPC de tu respuesta a `tools/call`, no necesita un arreglo `content` y aquí incluye los campos opcionales `statusMessage` y `pollIntervalMs`:599Responde con una tarea solo cuando la solicitud lleve la extensión; de lo contrario, la llamada falla con el error de herramienta `Unsupported result type 'task' for tools/call`. La llamada falla de la misma manera si tu respuesta no tiene `taskId` o no tiene un `status` válido. El objeto de tarea es el `result` JSON-RPC de tu respuesta a `tools/call`, no necesita un arreglo `content` y aquí incluye los campos opcionales `statusMessage` y `pollIntervalMs`:
600 600
601```json theme={null}601```json theme={null}
602{602{
613 613
614| Campo | Cómo lo maneja Claude Code |614| Campo | Cómo lo maneja Claude Code |
615| - | - |615| - | - |
616| `resultType` | Establécelo en `"task"` para marcar la respuesta como una tarea. Sin él, Claude Code interpreta la respuesta como un resultado normal |616| `resultType` | Establécelo en `"task"` para marcar la respuesta como una tarea. Sin él, Claude Code interpreta la respuesta como un resultado simple |
617| `taskId` | Obligatorio. Como máximo 128 caracteres ASCII imprimibles sin espacios, o Claude recibe un error de herramienta que empieza con `MCP server "<name>" returned a malformed task handle for tool "<tool>"`. Mantén el ID consultable entre conexiones, porque después de una reanudación Claude Code pregunta por él en una conexión nueva |617| `taskId` | Obligatorio. Como máximo 128 caracteres ASCII imprimibles sin espacios; de lo contrario, Claude recibe un error de herramienta que empieza con `MCP server "<name>" returned a malformed task handle for tool "<tool>"`. Mantén el ID respondible entre conexiones, porque después de una reanudación Claude Code pregunta por él en una conexión nueva |
618| `status` | Obligatorio. Uno de `working`, `input_required`, `completed`, `failed` o `cancelled`. Otro valor produce el error `Unsupported result type` |618| `status` | Obligatorio. Uno de `working`, `input_required`, `completed`, `failed` o `cancelled`. Otro valor produce el error `Unsupported result type` |
619| `createdAt`, `lastUpdatedAt`, `ttlMs` | Obligatorios según la extensión de tareas, y `ttlMs` puede ser `null`. Claude Code no descarta una tarea porque haya pasado su `ttlMs` |619| `createdAt`, `lastUpdatedAt`, `ttlMs` | Obligatorios según la extensión de tareas, y `ttlMs` puede ser `null`. Claude Code no descarta una tarea porque su `ttlMs` haya pasado |
620| `pollIntervalMs` | Opcional. Milisegundos entre solicitudes `tasks/get`, limitado a un valor entre 250 y 30000. Claude Code usa 2000 cuando el campo está ausente o es `null`, y vuelve a leer el valor de cada respuesta a `tasks/get` |620| `pollIntervalMs` | Opcional. Milisegundos entre solicitudes `tasks/get`, limitado a un valor entre 250 y 30000. Claude Code usa 2000 cuando el campo está ausente o es `null`, y vuelve a leer el valor de cada respuesta a `tasks/get` |
621| `statusMessage` | Opcional. `/tasks` muestra el valor de tu última respuesta a `tasks/get`, no de esta primera, y una respuesta que omite el campo lo borra. Un [mensaje de estado de Claude Code](#status-messages-on-an-mcp-task) puede ocupar su lugar |621| `statusMessage` | Opcional. `/tasks` muestra el valor de tu respuesta más reciente a `tasks/get`, no el de esta primera, y una respuesta que omite el campo lo borra. Un [mensaje de estado de Claude Code](#status-messages-on-an-mcp-task) puede ocupar su lugar |
622 622
623Claude Code acepta una respuesta de tarea que omite `createdAt`, `lastUpdatedAt` o `ttlMs`, o que establece `pollIntervalMs` en `null`. Antes de v2.1.317, la llamada fallaba en su lugar con el error `Unsupported result type`. Para que también funcione con esas versiones, envía los tres campos que requiere la extensión de tareas, y envía `pollIntervalMs` como número o no lo envíes.623Claude Code acepta una respuesta de tarea que omite `createdAt`, `lastUpdatedAt` o `ttlMs`, o que establece `pollIntervalMs` en `null`. Antes de v2.1.317, la llamada fallaba en su lugar con el error `Unsupported result type`. Para que también funcione con esas versiones, envía los tres campos que requiere la extensión de tareas, y envía `pollIntervalMs` como número o no lo envíes.
624 624
625En un servidor HTTP o de conector de claude.ai, la respuesta con la tarea tiene que empezar dentro del [temporizador por solicitud](#time-limits-on-mcp-tool-calls), así que acepta el trabajo y responde primero, y luego haz el trabajo.625En un servidor HTTP o de conector de claude.ai, la respuesta de tarea tiene que empezar dentro del [temporizador por solicitud](#time-limits-on-mcp-tool-calls), así que acepta el trabajo y responde primero, y luego haz el trabajo.
626 626
627#### Informar estado, resultados y preguntas627#### Informar estado, resultados y preguntas
628 628
629Justo 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ó:629Justo después de la respuesta de tarea, Claude Code envía `tasks/get` con `{ "taskId": ... }` y luego lo repite una vez por intervalo de sondeo. La extensión de tareas requiere 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ó:
630 630
631```json theme={null}631```json theme={null}
632{632{
645| Estado, método o respuesta | Cómo lo maneja Claude Code |645| Estado, método o respuesta | Cómo lo maneja Claude Code |
646| - | - |646| - | - |
647| `working` | Sigue sondeando |647| `working` | Sigue sondeando |
648| `completed` | Le entrega a Claude el resultado normal de `tools/call` en el objeto `result` de nivel superior. Un `isError: true` dentro de él se informa como un fallo |648| `completed` | Le da a Claude el resultado normal de `tools/call` en el objeto `result` de nivel superior. Un `isError: true` dentro de él se informa como un fallo |
649| `failed` | Le indica a Claude el `message` del objeto `error` de nivel superior `{ code, message, data }`, que la extensión de tareas exige en una tarea fallida. Sin ese `message`, Claude recibe `statusMessage` en su lugar, o si no, `Task failed` |649| `failed` | Le comunica a Claude el `message` del objeto `error` de nivel superior `{ code, message, data }`, que la extensión de tareas requiere en una tarea fallida. Sin ese `message`, Claude recibe `statusMessage` en su lugar, o en su defecto `Task failed` |
650| `cancelled` | Le indica a Claude `statusMessage`, o si no, `Task was cancelled by the server` |650| `cancelled` | Le comunica a Claude `statusMessage`, o en su defecto `Task was cancelled by the server` |
651| `input_required` | Lee `inputRequests`, un objeto que asigna una clave que tú eliges a `{ method, params }`. Claude Code responde a cada clave una vez mediante `tasks/update` con `{ taskId, inputResponses }`, donde `inputResponses` asigna la misma clave al resultado de esa solicitud. Las claves que superan las 16 por tarea se ignoran |651| `input_required` | Lee `inputRequests`, un objeto que asigna una clave que tú eliges a `{ method, params }`. Claude Code responde a cada clave una vez mediante `tasks/update` con `{ taskId, inputResponses }`, donde `inputResponses` asigna la misma clave al resultado de esa solicitud. Las claves que superan las 16 por tarea se ignoran |
652| Métodos en `inputRequests` | `elicitation/create` solo se atiende en sesiones interactivas de terminal, y `roots/list` en todas partes. Cuando Claude Code no puede atender una solicitud, le pide al servidor que cancele la tarea |652| Métodos en `inputRequests` | `elicitation/create` se atiende solo en sesiones interactivas de la terminal, y `roots/list` en todas partes. Cuando Claude Code no puede atender una solicitud, le pide al servidor que cancele la tarea |
653| Otro valor de `status` | Claude Code le pide al servidor que cancele la tarea y la informa a Claude como fallida |653| Otro valor de `status` | Claude Code le pide al servidor que cancele la tarea y se la informa a Claude como fallida |
654| Error JSON-RPC `-32602` | Se interpreta como un ID de tarea desconocido. Para una tarea en segundo plano, Claude Code sigue preguntando durante hasta cinco minutos y luego informa a Claude que el resultado es desconocido |654| Error JSON-RPC `-32602` | Se interpreta como un ID de tarea desconocido. Para una tarea en segundo plano, Claude Code sigue preguntando hasta cinco minutos y luego le informa a Claude que el resultado es desconocido |
655| `tasks/cancel` | Se envía, por ejemplo, cuando Claude o la persona detiene la tarea mientras el servidor está conectado. No se envía al salir |655| `tasks/cancel` | Se envía, por ejemplo, cuando Claude o la persona detiene la tarea mientras el servidor está conectado. No se envía al salir |
656| `tasks/result`, `tasks/list`, `notifications/tasks` | No se usan, así que incluye el resultado en tus respuestas a `tasks/get` |656| `tasks/result`, `tasks/list`, `notifications/tasks` | No se usan, así que incluye el resultado en tus respuestas a `tasks/get` |
657 657
658### Servidores MCP proporcionados por plugins658### Servidores MCP proporcionados por plugins
659 659
660[Los plugins](https://code.claude.com/docs/es/plugins/overview.md) pueden incluir servidores MCP que proporcionan herramientas e integraciones cuando habilitas el plugin.660Los [plugins](https://code.claude.com/docs/es/plugins/overview.md) pueden incluir servidores MCP que proporcionan herramientas e integraciones cuando habilitas el plugin.
661 661
662**Cómo funcionan los servidores MCP de plugins**:662**Cómo funcionan los servidores MCP de plugins**:
663 663
664* Los plugins definen servidores MCP en `.mcp.json` en la raíz del plugin o en línea en `plugin.json`664* Los plugins definen servidores MCP en `.mcp.json` en la raíz del plugin o en línea en `plugin.json`
665* Cuando habilitas un plugin, Claude Code inicia sus servidores MCP automáticamente665* Cuando habilitas un plugin, Claude Code inicia sus servidores MCP automáticamente
666* Claude Code ofrece las herramientas MCP de plugins junto con las herramientas MCP configuradas manualmente666* Claude Code ofrece las herramientas MCP de plugins junto con las herramientas MCP configuradas manualmente
667* Agregas y eliminas servidores de plugins instalando o desinstalando el plugin, no con comandos `/mcp`. Aún puedes [desactivar un servidor de plugin instalado](#disable-a-server-without-removing-it) en `/mcp`, lo que hace que Claude Code deje de conectarse a él sin eliminar el plugin667* Agregas y quitas servidores de plugins instalando o desinstalando el plugin, no con comandos `/mcp`. Aun así, puedes [desactivar un servidor de plugin instalado](#disable-a-server-without-removing-it) en `/mcp`, lo que impide que Claude Code se conecte a él sin quitar el plugin
668 668
669**Ejemplo de configuración MCP de plugin**:669**Ejemplo de configuración MCP de un plugin**:
670 670
671En `.mcp.json` en la raíz del plugin:671En `.mcp.json` en la raíz del plugin:
672 672
698}698}
699```699```
700 700
701**Características MCP de plugins**:701**Características de MCP en plugins**:
702 702
703* **Ciclo de vida automático**: los servidores se conectan y desconectan en estos momentos:703* **Ciclo de vida automático**: los servidores se conectan y desconectan en estos momentos:
704 * 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`](#server-status-detail) 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](https://code.claude.com/docs/es/errors.md#skipping-connection-recent-failure-cached)704 * Al iniciar 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 ya hayas usado antes puede mostrar en su lugar el [estado `cached`](#server-status-detail); 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](https://code.claude.com/docs/es/errors.md#skipping-connection-recent-failure-cached)
705 * 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](https://code.claude.com/docs/es/plugins/cli-reference.md#reload-plugins) 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ón705 * Si habilitas o deshabilitas un plugin durante una sesión, Claude Code conecta o desconecta sus servidores MCP cuando se aplica el cambio. [Aplicar cambios de plugins sin reiniciar](https://code.claude.com/docs/es/plugins/cli-reference.md#reload-plugins) describe cuándo ocurre eso. En una sesión sin una terminal interactiva, `/reload-plugins` no conecta ni desconecta los servidores MCP de plugins; esos cambios surten efecto en tu próxima sesión
706 * 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](https://code.claude.com/docs/es/agent-sdk/typescript.md#mcpsetserversresult) desde el Agent SDK sin nombrarlos706 * 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](https://code.claude.com/docs/es/agent-sdk/typescript.md#mcpsetserversresult) desde el Agent SDK sin nombrarlos
707 * Cuando [mueves la sesión con `/cd`](https://code.claude.com/docs/es/permissions#move-the-session-to-another-directory) 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 cambio707 * Cuando [mueves la sesión con `/cd`](https://code.claude.com/docs/es/permissions#move-the-session-to-another-directory) en la v2.1.246 o posterior, Claude Code conecta los servidores de los plugins que habilita la configuración del nuevo directorio y desconecta los servidores de los plugins que ya no están habilitados, así que no necesitas ejecutar `/reload-plugins` después del cambio
708 * En [sesiones en la nube](https://code.claude.com/docs/es/claude-code-on-the-web.md), 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 conecte708 * En las [sesiones en la nube](https://code.claude.com/docs/es/claude-code-on-the-web.md), una llamada MCP a un servidor de plugin que aún no está conectado, por ejemplo justo después de que se reactive una sesión inactiva, inicia el servidor bajo demanda y espera a que se conecte
709* **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](https://code.claude.com/docs/es/plugins/components.md#path-variables-and-persistent-data), y `${CLAUDE_PROJECT_DIR}` a la raíz estable del proyecto. La sustitución se aplica a:709* **Marcadores de ruta**: `${CLAUDE_PLUGIN_ROOT}` se resuelve en el directorio de instalación del plugin, `${CLAUDE_PLUGIN_DATA}` en su directorio de [estado persistente](https://code.claude.com/docs/es/plugins/components.md#path-variables-and-persistent-data), y `${CLAUDE_PROJECT_DIR}` en la raíz estable del proyecto. La sustitución se aplica a:
710 * servidores `stdio`: `command`, `args`, `env`710 * Servidores `stdio`: `command`, `args`, `env`
711 * servidores `http`, `sse`, y `ws`: `url`, `headers`, y `headersHelper`711 * Servidores `http`, `sse` y `ws`: `url`, `headers` y `headersHelper`
712* **Acceso al entorno del usuario**: acceso a las mismas variables de entorno que los servidores configurados manualmente712* **Acceso al entorno del usuario**: acceso a las mismas variables de entorno que los servidores configurados manualmente
713* **Múltiples tipos de transporte**: soporte para transportes stdio, SSE, HTTP, y WebSocket, aunque el soporte de transporte puede variar según el servidor713* **Múltiples tipos de transporte**: compatibilidad con los transportes stdio, SSE, HTTP y WebSocket, aunque la compatibilidad de transporte puede variar según el servidor
714 714
715Los servidores de plugins aparecen en `/mcp` con indicadores que muestran que provienen de plugins.715Los servidores de plugins aparecen en `/mcp` con indicadores que muestran que provienen de plugins.
716 716
717`claude mcp get` oculta los valores configurados para el servidor stdio o WebSocket de un plugin, porque pueden contener credenciales:717`claude mcp get` oculta los valores configurados para el servidor stdio o WebSocket de un plugin, porque pueden contener credenciales:
718 718
719* **Servidor stdio**: imprime `Command: stdio`, una línea `Args:` vacía, y cada variable de entorno como `NAME=[REDACTED]`719* **Servidor stdio**: muestra `Command: stdio`, una línea `Args:` vacía y cada variable de entorno como `NAME=[REDACTED]`
720* **Servidor WebSocket**: imprime `URL: ws` y cada encabezado como `<name>: [REDACTED]`, y `claude mcp list` muestra `ws` en lugar de la URL720* **Servidor WebSocket**: muestra `URL: ws` y cada encabezado como `<name>: [REDACTED]`, y `claude mcp list` muestra `ws` en lugar de la URL
721 721
722Para ver lo que configuró el plugin, [busca el plugin en el disco](https://code.claude.com/docs/es/plugins/loading.md#find-plugins-on-disk) y lee su `.mcp.json` o `plugin.json`.722Para ver lo que configuró el plugin, [busca el plugin en el disco](https://code.claude.com/docs/es/plugins/loading.md#find-plugins-on-disk) y lee su `.mcp.json` o `plugin.json`.
723 723
724**Nombres de herramientas MCP de plugins**:724**Nombres de herramientas MCP de plugins**:
725 725
726Las 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:726Las herramientas de un servidor MCP incluido en un plugin incluyen tanto el nombre del plugin como la clave del servidor en su nombre invocable. La forma completa es `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`, donde cualquier carácter fuera de `A-Z`, `a-z`, `0-9`, `_` y `-` se reemplaza por `_`. Para el servidor `database-tools` incluido en un plugin llamado `my-plugin`, una herramienta `query` se puede invocar como:
727 727
728```728```
729mcp__plugin_my-plugin_database-tools__query729mcp__plugin_my-plugin_database-tools__query
730```730```
731 731
732Usa este nombre completo cuando hagas referencia a la herramienta en [reglas de permisos](https://code.claude.com/docs/es/permissions.md), la lista `allowed-tools` de un skill, el [campo `tools` de un subagente](https://code.claude.com/docs/es/sub-agents#available-tools), o un [matcher de hook](https://code.claude.com/docs/es/hooks.md#match-mcp-tools). 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.732Usa este nombre completo cuando hagas referencia a la herramienta en [reglas de permisos](https://code.claude.com/docs/es/permissions.md), la lista `allowed-tools` de un skill, el [campo `tools` de un subagente](https://code.claude.com/docs/es/sub-agents#available-tools) o un [matcher de hook](https://code.claude.com/docs/es/hooks.md#match-mcp-tools). Un matcher de hook escrito con la clave del servidor sin prefijo, como `mcp__database-tools__.*`, nunca se activa para un servidor incluido en un plugin.
733 733
734El 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`](https://code.claude.com/docs/es/hooks#mcp-tool-hook-fields).734El servidor en sí se registra con el nombre con ámbito `plugin:<plugin-name>:<server-name>`, como `plugin:my-plugin:database-tools`. Usa ese nombre donde se espere el nombre de un servidor configurado, como en el [campo `server` de un hook `mcp_tool`](https://code.claude.com/docs/es/hooks#mcp-tool-hook-fields).
735 735
736Consulta la [referencia de componentes de plugins](https://code.claude.com/docs/es/plugins/components.md#mcp-servers) para obtener detalles sobre cómo incluir servidores MCP en plugins.736Consulta la [referencia de componentes de plugins](https://code.claude.com/docs/es/plugins/components.md#mcp-servers) para obtener detalles sobre cómo incluir servidores MCP en plugins.
737 737
1800* **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.1800* **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.
1801* **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.1801* **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.
1802 1802
1803Antes 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`.
1804
1805Controla el comportamiento de la búsqueda de herramientas con la variable de entorno `ENABLE_TOOL_SEARCH`:1803Controla el comportamiento de la búsqueda de herramientas con la variable de entorno `ENABLE_TOOL_SEARCH`:
1806 1804
1807| Valor | Comportamiento |1805| Valor | Comportamiento |
