SpyBara
Go Premium

mcp-quickstart.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 218 additions and 252 deletions.

2026
Thu 1 23:59 Thu 15 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Wed 28 23:57 Fri 30 23:01

Conectarse a servidores MCP

Agregue un servidor MCP a Claude Code, verifique la conexión y encuentre la configuración en el disco.

El Protocolo de Contexto de Modelo (MCP) permite que Claude Code utilice herramientas más allá de su conjunto integrado, como buscar en un rastreador de problemas, consultar una base de datos o controlar un navegador web. Estas herramientas provienen de servidores MCP, que se ejecutan en su máquina o como servicios alojados.

Esta guía le muestra cómo conectar un servidor MCP de extremo a extremo con la CLI de Claude Code. Al final, tendrá un servidor conectado y respondiendo, sabrá dónde vive su configuración en el disco y sabrá cómo solucionar los errores de conexión más comunes.

[!NOTE]

También puede agregar servidores MCP desde otras superficies, incluida la aplicación de escritorio, VS Code y la web. Consulte Conectarse desde otras superficies.

Para cada forma de conectar y configurar servidores MCP en Claude Code, consulte la referencia de MCP.

Antes de comenzar

Asegúrese de tener:

  • Claude Code instalado y autenticado
  • Una terminal abierta en un directorio de proyecto. Cualquier directorio funciona, incluido uno vacío.

Agregar y verificar un servidor

El ejemplo a continuación se conecta al servidor MCP de documentación de Claude Code, un servidor alojado con búsqueda de texto completo en los documentos de Claude Code. No requiere autenticación ni ninguna configuración especial, por lo que funciona bien como primer servidor para probar el flujo de configuración.

Los pasos son los mismos para cualquier servidor: agréguelo, verifique el estado de la conexión, luego úselo en una sesión, con un paso de limpieza opcional al final. Algunos servidores agregan un paso, como un inicio de sesión del navegador, que se muestra en Ejemplos adicionales de servidores MCP. Para más servidores para conectar, explore el Directorio de Anthropic.

1. Agregar el servidor MCP

Registre el servidor con Claude Code. Ejecute esto en su terminal, no dentro de una sesión claude: está configurando el servidor antes de iniciar una conversación.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Las partes del comando:

  • claude mcp add: registra un servidor con Claude Code.
  • --transport http: el servidor se aloja en una URL en lugar de ejecutarse como un proceso local.
  • claude-code-docs: un nombre que usted elige. Llamar al mismo servidor docs funcionaría de manera idéntica. Claude Code utiliza el nombre que elija para etiquetar las herramientas del servidor en la salida de Claude y para referirse al servidor en comandos como claude mcp remove.
  • https://code.claude.com/docs/mcp: la URL donde se aloja el servidor.

El comando imprime una confirmación como Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config, seguida de una línea File modified: que muestra el archivo de configuración que escribió. La parte local config significa que el servidor está registrado para usted, en este proyecto: si inicia Claude Code en un proyecto diferente, este servidor no está activo allí. Para registrar un servidor una vez para todos sus proyectos, agréguelo en el ámbito del usuario, cubierto en Cambiar el ámbito del servidor.

2. Verificar el estado de la conexión

Confirme que el servidor aparece en su lista de servidores y verifique su estado:

claude mcp list

El servidor aparece con un indicador de estado:

Estado Significado
✔ Connected Listo para usar. Esto es lo que debería ver para claude-code-docs
! Connected · tools fetch failed El servidor se conectó pero no pudo enumerar sus herramientas. Ejecute claude mcp get <name> para obtener el detalle del error
! Needs authentication El servidor es accesible pero necesita un inicio de sesión del navegador, o un token pasado con --header. Consulte Conectar un servidor que requiere inicio de sesión
✘ Failed to connect El servidor no respondió. Consulte Solución de problemas
✘ Connection error El intento de conexión lanzó un error. Consulte Solución de problemas
⏸ Pending approval (run `claude` to approve) Un servidor con ámbito de proyecto que aún no ha aprobado. Consulte Editar .mcp.json directamente
⊘ Disabled for this project (re-enable via /mcp) Un servidor desactivado para este proyecto por la lista disabledMcpServers del proyecto. Consulte Deshabilitar un servidor sin eliminarlo

Algunas consolas heredadas de Windows, como la consola predeterminada en Windows 10, no admiten estos glifos Unicode y muestran √ y × en lugar de ✔ y ✘.

3. Usar el servidor

Inicie una sesión y pida a Claude que use el nuevo servidor por nombre:

claude

Use the claude-code-docs server to look up what MCP_TIMEOUT does

[!NOTE]

Normalmente no necesita nombrar un servidor en su indicación, ya que Claude elige herramientas relevantes por su cuenta. Nombrarlo aquí garantiza que la demostración pase por el nuevo servidor en lugar de otra herramienta, como web fetch, que podría responder la misma pregunta.

Si Claude Code solicita permiso la primera vez que Claude llama al servidor, apruébelo. La llamada de herramienta en la salida de Claude está etiquetada con el nombre del servidor, que es cómo confirma que la respuesta provino del servidor MCP en lugar del conocimiento integrado de Claude.

4. Eliminar el servidor

Este paso es opcional. Cuando termine de experimentar, puede eliminar el servidor:

claude mcp remove claude-code-docs

El comando confirma con Removed MCP server "claude-code-docs" from local config y una línea File modified: que muestra el archivo que actualizó.

[!NOTE]

Cada servidor conectado ocupa algo de espacio en la ventana de contexto de Claude porque sus nombres de herramientas e instrucciones del servidor se cargan en cada sesión. Eliminar servidores que ya no usa mantiene ese espacio libre.

Dónde se guardan los servidores

El comando claude mcp add escribe los detalles del servidor en un archivo de configuración. De forma predeterminada, registra el servidor en el ámbito local: privado para usted, activo solo en el proyecto actual. Pase --scope user para registrarlo una vez para todos sus proyectos, o --scope project para compartirlo con sus compañeros de equipo. Cambiar el ámbito del servidor explica ambos.

[!NOTE]

claude mcp add funciona igual en cada shell, incluidos PowerShell y Command Prompt. Dentro de una sesión claude, use el comando /mcp para verificar y administrar servidores que ya ha agregado.

Hay otras formas de agregar un servidor, cada una con su propia sección:

Encontrar su configuración en el disco

El comando claude mcp add escribe el servidor en uno de tres ámbitos, almacenados en dos archivos, dependiendo de la bandera --scope. No necesita editar estos archivos directamente, pero saber dónde están ayuda con la depuración y el control de versiones.

Ámbito Archivo Disponible para
local ~/.claude.json, bajo la entrada para este proyecto Solo usted, solo este proyecto. El predeterminado
project .mcp.json en la raíz de su proyecto Todos los que clonan el proyecto
user ~/.claude.json, bajo la clave mcpServers de nivel superior Solo usted, todos los proyectos

En Windows, ~/.claude.json se resuelve a %USERPROFILE%\.claude.json, típicamente C:\Users\YourName\.claude.json. Si ha establecido CLAUDE_CONFIG_DIR, Claude Code lee .claude.json desde dentro de ese directorio en su lugar.

Ejecute claude mcp get claude-code-docs para ver qué ámbito contiene la definición de un servidor. Para cómo interactúan los ámbitos cuando el mismo servidor se define en más de uno, consulte Ámbitos de instalación de MCP.

Cambiar el ámbito del servidor

El ámbito de un servidor se fija cuando lo agrega, por lo que cambiar el ámbito significa eliminar la entrada y volver a agregarla en la nueva. Ambos casos a continuación comienzan eliminando la entrada local del primer tutorial, por lo que el servidor tiene solo una definición. Si ya lo eliminó al final de ese tutorial, omita este comando:

claude mcp remove claude-code-docs --scope local

Usar un servidor en todos sus proyectos

Vuelva a agregar el servidor en el ámbito user para hacerlo activo en cada proyecto que abra, aún privado para usted:

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

Compartir un servidor con su equipo

Vuelva a agregar el servidor en el ámbito project, que escribe en .mcp.json en la raíz del proyecto:

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

Confirme .mcp.json en el control de versiones. Los compañeros de equipo que clonan el repositorio e inician Claude Code ven un mensaje para aprobar el servidor, luego se conecta para ellos también.

Ejemplos adicionales de servidores MCP

El primer tutorial utilizó un servidor alojado que se conecta sin ningún inicio de sesión. Los ejemplos a continuación cubren las otras dos formas comunes, con el mismo flujo de agregar, verificar, usar.

Agregar un servidor local

Un servidor stdio local es un programa que Claude Code inicia como un subproceso en su máquina, en lugar de un servicio al que accede a través de una URL. Use uno para herramientas que necesitan acceso a recursos locales como un navegador, su sistema de archivos o un socket de base de datos.

El servidor MCP de Playwright es uno bueno para probar: le da a Claude un navegador que puede navegar, hacer clic y leer, y no necesita ninguna cuenta. Se ejecuta a través de npx, por lo que requiere Node.js 18 o posterior.

1. Agregar el servidor Playwright

Registre el servidor con el comando que Claude Code debe ejecutar para iniciarlo:

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

Este comando difiere del ejemplo alojado de tres maneras:

  • No hay bandera --transport, porque los servidores locales usan el transporte predeterminado stdio.
  • Todo después del separador -- es el comando que Claude Code ejecuta para iniciar el servidor.
  • -y le dice a npx que instale el paquete sin preguntar.

El comando imprime una confirmación como Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config, seguida de una línea File modified: que muestra el archivo de configuración que escribió.

Playwright controla cualquier Chrome que ya esté instalado en su máquina. Para usar un navegador diferente, agregue --browser con el nombre del navegador, por ejemplo --browser firefox, después de @playwright/mcp@latest.

2. Verificar la conexión

La confirmación Added significa que la entrada se guardó, no que el comando se ejecute. Verifique la conexión:

claude mcp list

La primera verificación puede mostrar ✘ Failed to connect mientras npx descarga el paquete, así que espere un momento y ejecútelo de nuevo. Una vez que se completa la descarga, el estado cambia a ✔ Connected. Si aún muestra ✘ Failed to connect después de un par de reintentos, consulte Solución de problemas.

3. Usar el navegador

Dale a Claude una tarea que necesite el navegador:

Use playwright to open https://example.com and tell me the page title

Se abre una ventana del navegador para que pueda verlo funcionar, y las llamadas de herramienta en la salida de Claude están etiquetadas con el nombre del servidor playwright y la acción, como browser_navigate.

Intente apuntarlo a su servidor de desarrollo local para verificar que una página aún se renderiza después de un cambio, o haga que recorra un informe de error paso a paso.

Conectar un servidor que requiere inicio de sesión

Servicios alojados como Sentry, Linear y Notion ejecutan sus servidores MCP detrás de OAuth: agrega la URL del servidor, luego inicia sesión a través de su navegador.

Los pasos a continuación usan Sentry como ejemplo. Para conectar un servicio diferente, sustituya su URL, que puede encontrar en el Directorio de Anthropic o en la documentación del servicio.

1. Agregar el servidor

El comando add es el mismo que para el servidor de documentos, con la URL de Sentry:

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

Después de agregar, claude mcp list muestra el servidor con ! Needs authentication. Eso es esperado: el siguiente paso completa el inicio de sesión.

2. Autenticarse en su navegador

Inicie una sesión de Claude Code y abra el panel MCP:

/mcp

Seleccione sentry de la lista, presione Intro y elija Authenticate. Su navegador se abre a la página de inicio de sesión de Sentry. Apruebe la conexión allí.

De vuelta en Claude Code, el estado del servidor cambia a conectado. Si el inicio de sesión falla o el navegador no se abre, consulte Solución de problemas.

3. Usar el servidor

Pregúntele a Claude algo que necesite el servicio, como What Sentry projects do I have access to?, y busque llamadas de herramienta etiquetadas con el nombre del servidor sentry en su salida.

Los servidores que se autentican con un token estático en lugar de OAuth toman el token en el momento de agregar con --header "Authorization: Bearer <token>". Consulte el ejemplo de GitHub para una versión trabajada.

Editar .mcp.json directamente

Cada archivo en la tabla de ámbitos utiliza el mismo formato JSON para entradas de servidor. Esta sección edita .mcp.json, el archivo de ámbito de proyecto. Es el que más vale la pena escribir a mano porque se verifica en el repositorio, donde también funciona como configuración como código para su equipo.

Cree .mcp.json en la raíz de su proyecto. El ejemplo a continuación define ambos servidores de esta guía, el servidor de documentos alojado alcanzado a través de HTTP y el servidor Playwright como un proceso stdio local:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Los campos difieren según el tipo de servidor:

  • Para servidores HTTP, url es el punto final al que se conecta Claude Code.
  • Para servidores stdio, command y args son el programa que ejecuta.

Después de guardar el archivo, inicie una nueva sesión de Claude Code en el proyecto. Claude Code lee .mcp.json al iniciar.

La primera vez que Claude Code ve un servidor con ámbito de proyecto, le pide que lo apruebe. El mensaje existe para que un repositorio que Clone no pueda lanzar procesos en su máquina sin su consentimiento. Apruebe el mensaje, o ejecute /mcp para aprobar más tarde si lo perdió.

Una vez que haya aprobado, ejecute /mcp y verifique que los servidores se muestren como conectados. Si uno muestra un error en su lugar, consulte Solución de problemas.

Conectarse desde otras superficies

Esta guía utiliza los comandos CLI claude mcp, pero cada superficie de Claude Code puede conectarse a servidores MCP:

Solución de problemas

Si un servidor no se conecta, revisa su estado con /mcp dentro de una sesión o con claude mcp list desde tu shell, y luego busca el síntoma correspondiente a continuación. El panel /mcp también te permite reconectar o autenticarte sin salir de la sesión.

/mcp muestra No MCP servers configured

Claude Code no encontró ningún servidor para el directorio actual. Las causas más comunes:

  • Ejecutaste claude mcp add desde un proyecto diferente. Los servidores con alcance local están vinculados al proyecto donde los agregaste: la raíz del repositorio, o el directorio exacto si no estabas en un repositorio de git. Vuelve a agregar el servidor desde el proyecto en el que estás ahora, o agrégalo con --scope user para que no quede vinculado a un proyecto.
  • Editaste un archivo de configuración en la ruta equivocada. Los archivos correctos son ~/.claude.json y <project>/.mcp.json. Claude Code no lee rutas como ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json ni %APPDATA%\Claude\mcp.json. Para servidores con alcance de usuario, ejecuta claude mcp add --scope user, que escribe en la clave mcpServers de ~/.claude.json; para servidores con alcance de proyecto, edita .mcp.json en la raíz del proyecto.
  • Escribiste una entrada mal formada en .mcp.json. Claude Code omite esa entrada y aun así carga las demás. Ejecuta claude mcp list desde tu shell y busca la advertencia de análisis, que indica el campo problemático.

El estado muestra Failed to connect o Connection error

Ambos estados significan que el servidor no se inició o que la URL no respondió. También pueden aparecer en servidores HTTP que rechazan el token que configuraste en headers.Authorization; un servidor que requiere un token que no has configurado muestra ! Needs authentication en su lugar, lo cual se trata en Conectar un servidor que requiere inicio de sesión.

Tu primer paso depende del estado que veas:

  • Failed to connect: comienza con el detalle del error que aparece en el propio estado. claude mcp list y claude mcp get <name> muestran el estado HTTP o el código de error y cualquier texto de error que haya devuelto el servidor, que a menudo indica el problema directamente, como un encabezado faltante o un token rechazado. Antes de v2.1.219, Failed to connect mostraba solo el estado sin más información, y necesitabas las comprobaciones con curl y con el comando que se describen más adelante en esta sección para encontrar la causa.
  • Connection error: Claude Code no agrega ningún detalle a este estado en ninguna versión, así que ve directamente a las comprobaciones con curl y con el comando que se describen más adelante en esta sección.

Si el detalle apunta a una credencial o a una URL, revisa también las advertencias en la salida de claude mcp list. Claude Code marca los valores de configuración con espacios en blanco ocultos al inicio o al final, una causa común de fallos de autenticación después de pegar un token.

Si un servidor HTTP devuelve 404 Not Found, Claude Code muestra MCP endpoint not found at <origin>. Check the URL in your MCP config. cuando seleccionas el servidor en /mcp. El mensaje indica el origen de la URL, como https://mcp.example.com, sin su ruta, así que ejecuta claude mcp get <name> para ver la URL completa que configuraste. Compara su ruta con la ruta del endpoint MCP documentada por el servidor, luego ejecuta claude mcp remove <name> y vuelve a agregarlo con la URL correcta. Antes de v2.1.219, el mensaje también incluía la ruta de la URL, y antes de v2.1.191, un 404 mostraba un mensaje genérico Error POSTing to endpoint sin la URL.

Para servidores HTTP, confirma que la URL es accesible desde tu máquina:

curl -I https://mcp.sentry.dev/mcp

En PowerShell, usa curl.exe en lugar de curl para que la solicitud vaya al binario real de curl y no al alias Invoke-WebRequest.

La respuesta te indica qué tipo de problema tienes:

  • Un 404 o 405: el servidor está activo. Muchos endpoints MCP solo responden a solicitudes POST, así que esto igualmente confirma que la URL es accesible desde tu máquina.
  • Un 401 o 403: el servidor está activo y necesitas autenticarte. Usa el inicio de sesión en el navegador que se describe en Conectar un servidor que requiere inicio de sesión, o, para servidores que en su lugar aceptan un token, como el de GitHub, pásalo con --header "Authorization: Bearer <token>" en el comando claude mcp add.
  • Ninguna respuesta: revisa la URL y tu red.

Para servidores stdio, ejecuta el comando configurado directamente en tu terminal para ver el error subyacente. Para el servidor de Playwright de esta guía, ejecuta:

npx -y @playwright/mcp@latest

Lo que ocurra a continuación te indica dónde está el problema:

  • El comando se inicia y espera una entrada: el servidor en sí funciona.

    Ejecuta claude mcp get <name> y confirma que el comando que aparece ahí coincide con el que acabas de ejecutar. Si el comando mostrado difiere del que escribiste, probablemente omitiste el separador -- antes del comando del servidor. Elimina el servidor y vuelve a agregarlo con -- en su lugar. Si escribiste .mcp.json a mano, revisa su sintaxis y ubicación. Antes de v2.1.285, claude mcp get no mostraba ninguna línea Command para una entrada stdio guardada sin un campo type, como una entrada de .mcp.json escrita a mano. En esas versiones, ejecuta claude mcp list en su lugar, que muestra la línea de comando en cualquier caso.

  • El comando da error: el mensaje indica lo que falta, como Node.js o un navegador.

Se agotó el tiempo de espera de la conexión al iniciar

El servidor tardó más que el tiempo de espera de inicio predeterminado de 30 segundos. La primera ejecución de un servidor stdio puede ser lenta mientras npx descarga el paquete. Aumenta el límite con la variable de entorno MCP_TIMEOUT, en milisegundos:

MCP_TIMEOUT=60000 claude

En PowerShell, define la variable antes del comando en la misma línea:

$env:MCP_TIMEOUT = "60000"; claude

Antes de v2.1.299, a algunas conexiones a servidores HTTP que estaban activos se les agotaba el tiempo de espera al iniciar, sin importar MCP_TIMEOUT. Si usas una de esas versiones y a un servidor HTTP que está activo se le sigue agotando el tiempo de espera después de aumentar el límite, actualiza Claude Code.

El servidor ya existe

Ya agregaste un servidor con ese nombre en el mismo alcance. Elimina primero la entrada existente o elige un nombre diferente:

claude mcp remove claude-code-docs

Si el nombre existe en más de un alcance, remove informa exists in multiple scopes. Pasa --scope para elegir qué copia eliminar, por ejemplo claude mcp remove claude-code-docs --scope local.

El servidor se conecta pero no aparecen herramientas

Ejecuta /mcp dentro de una sesión y selecciona el servidor para ver su lista de herramientas. Si la lista está vacía, el servidor se inició pero no registró ninguna herramienta, lo que normalmente significa que le falta una variable de entorno obligatoria, como una clave de API.

Pasa la variable con --env KEY=value en claude mcp add, o en el campo env de la entrada del servidor en .mcp.json. La documentación del servidor indica las variables que necesita.

Antes de v2.1.302, /mcp mostraba el estado tools fetch failed para un servidor que usaba la revisión del protocolo 2026-07-28 y que omitía resultType, ttlMs o cacheScope en sus respuestas. Si usas una de esas versiones y un servidor muestra ese estado, actualiza Claude Code.

Los cambios en .mcp.json no surten efecto

Claude Code lee .mcp.json al inicio de la sesión. Sal y reinicia la sesión después de editar el archivo.

Si tus servidores siguen sin aparecer, ejecuta claude mcp list y busca una advertencia de análisis. Claude Code omite las entradas mal formadas y muestra ahí el campo problemático.

Si anteriormente rechazaste el servidor cuando se te pidió confirmación, restablece las aprobaciones del proyecto:

claude mcp reset-project-choices

El inicio de sesión con OAuth falla o el navegador no se abre

Ejecuta /mcp, selecciona el servidor y elige Authenticate de nuevo. Si el navegador no se abre automáticamente, copia la URL que aparece en la terminal y ábrela manualmente. Consulta Autenticarse con servidores MCP remotos para conocer los puertos de callback fijos y las credenciales preconfiguradas.

Próximos pasos

Con un servidor conectado, explore el resto de lo que MCP permite: