Conectar un servidor MCP a Claude: Desktop, claude.ai y Claude Code

Para conectar un servidor MCP a Claude hay tres vías, y la tuya depende de dónde viva el servidor. Si es local (un proceso en tu máquina que habla por stdio), va al archivo de configuración de Claude Desktop o a Claude Code. Si es remoto (una URL con Streamable HTTP), lo añades como conector personalizado en claude.ai, que vale también para Claude Desktop, o con un comando en Claude Code.

Aquí tienes los pasos y las configuraciones literales de la documentación oficial. También verás cómo comprobar que funciona, qué significan los errores típicos y qué mirar antes de conectar un servidor ajeno.

Si todavía no tienes un servidor, empieza por los tutoriales para crearlo en TypeScript o en Python. Si algún término no te suena (host, tool, stdio), el glosario de MCP lo resume en una línea.

¿Qué vía uso: Claude Desktop, claude.ai o Claude Code?

Decide dónde se ejecuta el servidor y, para los conectores, qué plan tienes.

Caso	Claude Desktop	claude.ai (web)	Claude Code
Servidor local (stdio)	claude_desktop_config.json o extensión .mcpb	No aplica	claude mcp add <nombre> -- <comando>
Servidor remoto (HTTP)	Conector personalizado (misma cuenta que claude.ai)	Conector personalizado en Customize > Connectors	claude mcp add --transport http <nombre> <url>
Planes y límites documentados	Extensiones de escritorio para todos los usuarios de Desktop	Free, Pro, Max, Team y Enterprise; Free, un solo conector personalizado. En Team y Enterprise lo añade un Owner	Las fuentes no fijan límites por plan; tres ámbitos: local, project y user

Los conectores no son de un cliente concreto. claude.ai, Claude Desktop, la app móvil, Cowork y Claude Code comparten la misma infraestructura de conectores.

La documentación oficial, además, solo muestra entradas command y args en claude_desktop_config.json. Así que, para un remoto, el camino documentado en Desktop es el conector.

¿Cómo conecto un servidor local a Claude Desktop?

Claude Desktop (macOS y Windows) declara los servidores locales en un JSON que la app crea si no existe. Para abrirlo, usa el menú Claude de la barra del sistema, no los ajustes de dentro de la ventana, y ve a Settings… > pestaña Developer > Edit Config. El archivo está en:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cada servidor es una entrada de mcpServers con el comando que Desktop lanzará. Este es el ejemplo de la guía oficial, con el servidor de referencia Filesystem limitado a dos carpetas. En Windows, las rutas van con \\.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

Fuente: Connect to local MCP servers, documentación de MCP 2026-07-28.

Como el servidor se lanza con npx, necesitas Node.js. Las variables de entorno van en un objeto env dentro de la entrada. Después de guardar, la guía indica «completely quit Claude Desktop and restart it».

Ten en cuenta que «The server runs with your user account permissions, so it can perform any file operations you can perform manually». Por eso el ejemplo se limita a dos carpetas. Cada acción te pide aprobación antes de ejecutarse.

Extensiones de escritorio (.mcpb)

La otra vía local son las extensiones. Un MCP Bundle es «a zip archive containing a local MCP server and a manifest.json, which Claude Desktop installs in a single click the way a browser installs an extension».

Puedes instalarlo con doble clic en el .mcpb, arrastrándolo a la ventana o desde Settings > Extensions > Advanced settings > Install Extension…. En los tres casos ves una pantalla para revisar permisos y rellenar la configuración. Desktop trae su propio Node.js y cifra los campos sensibles con Keychain (macOS) o Credential Manager (Windows).

Necesitas la sesión iniciada en claude.ai. La organización puede desactivar las extensiones, y en ese caso Extensions no aparece en los ajustes.

¿Cómo añado un servidor remoto en claude.ai?

Un servidor remoto se añade como conector personalizado, desde la interfaz y sin archivo de configuración. Estos son los pasos del artículo de soporte de Claude para Free, Pro y Max, resumidos:

1. Ve a Customize > Connectors (https://claude.ai/customize/connectors).
2. Pulsa + Add y después Add custom connector.
3. Escribe un nombre para el conector.
4. Pega la URL del servidor MCP remoto y pulsa Continue.
5. Revisa los ajustes de autenticación que Claude ha detectado y cámbialos si el servidor necesita otra cosa.
6. Pulsa Add.

En el paso 5 eliges dos cosas. En Authentication, entre «Sign in now», «Sign in when needed» o «No sign in». En OAuth client, entre tres opciones:

• «Use Claude’s published identity», la recomendada si el servidor admite ese método.
• «Register automatically», el registro dinámico, que funciona con la mayoría de los servidores.
• «Use your own OAuth client».

Request headers, para claves de API fijas, está en beta para un grupo limitado de organizaciones. Elige bien, porque «You can’t change authentication settings after you add a connector». Para cambiarlos tendrías que quitar el conector y añadirlo de nuevo.

En Team y Enterprise, el conector lo añade un Owner desde Organization settings > Connectors (Add > Custom). En Enterprise también puede hacerlo quien tenga un rol con «Manage access to Libraries». Cada miembro lo ve con la etiqueta Custom y pulsa Connect para autenticarse con su cuenta.

En Claude Desktop se añade igual. La guía de modelcontextprotocol.io lo sitúa en Settings (Ctrl+Comma) > Connectors > Add > Add custom connector. La documentación de Claude, más reciente, usa Customize > Connectors.

Qué tiene que cumplir el servidor

El conector lo abre la infraestructura de Anthropic, no tu navegador:

• Accesible desde internet. «Remote MCP servers must be publicly internet-accessible from Anthropic’s infrastructure». Si está en una red privada, tienes que permitir las IP de Anthropic o usar MCP tunnels.
• Solo IPv4. Un nombre que solo publica registros AAAA no es alcanzable.
• Streamable HTTP. Una URL que termina en /sse selecciona el HTTP+SSE heredado, que está «being deprecated».
• OAuth con PKCE S256, la URI de redirección https://claude.ai/api/mcp/auth_callback y una respuesta de /token en menos de 10 segundos.
• Límites: unos 150.000 caracteres por resultado de tool y 240 segundos por llamada. No hay suscripciones a resources ni sampling.

Si el servidor corre en tu portátil, usa un túnel (Cloudflare Tunnel o ngrok). Si usas createMcpExpressApp() del SDK de TypeScript, el túnel recibe 403 Invalid Host: <hostname> hasta que añades su nombre a allowedHosts.

Pruébalo con un servidor real: el de DesarrolloMCP

Si aún no tienes un servidor remoto propio, puedes practicar estos pasos con el de esta web. Son dos direcciones (endpoints) y ambas son de solo lectura:

• https://desarrollomcp.com/mcp es pública y no pide cuenta ni inicio de sesión. Tiene seis herramientas: buscar, ver_temario, ver_leccion, ver_planes, listar_articulos y leer_articulo.
• https://desarrollomcp.com/mcp/alumno usa OAuth 2.1 (el flujo de autorización que permite dar permiso sin compartir la contraseña; está en el glosario) y la cuenta de la web. Añade mi_cuenta, mi_progreso y leer_leccion, que lee las lecciones de tu nivel, con un límite aproximado de 60 lecturas de lección al día. Es una buena manera de ver el flujo de autorización al conectar el servidor.

Los pasos para Claude, ChatGPT, Claude Code y otros clientes están en Usa el curso desde Claude y ChatGPT. El acceso se retira cuando quieras en tu panel, en Aplicaciones conectadas.

¿Y en Claude Code?

Los tutoriales de TypeScript y Python lo explican paso a paso con un servidor real. Aquí va lo esencial:

# HTTP (recomendado para servidores remotos)
claude mcp add --transport http <name> <url>
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# stdio (proceso local)
claude mcp add [options] <name> -- <command> [args...]
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Fuente: Claude Code: MCP.

En stdio, el -- separa las opciones de Claude Code del comando del servidor. El nombre no puede ir justo después de --env, porque la CLI lo leería como otro par.

Con --scope eliges el ámbito:

• local, el de por defecto: solo este proyecto, en ~/.claude.json.
• project: escribe .mcp.json en la raíz para que puedas versionarlo.
• user: todos tus proyectos.

En .mcp.json, las entradas remotas llevan type:

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

Fuente: Claude Code: MCP.

Sin type, Claude Code toma una entrada con url por stdio y la omite. En sesiones interactivas, te pide aprobación antes de usar los servidores de un .mcp.json. Si un nombre se repite, la precedencia es local > project > user > plugins > conectores de claude.ai.

¿Cómo compruebo que el servidor está conectado?

Claude Desktop (servidor local). Tras reiniciar, pulsa «Add files, connectors, and more /» (abajo a la izquierda del cuadro de mensaje) > Connectors > Manage connectors y elige el servidor para ver sus tools.

Los registros están en ~/Library/Logs/Claude (macOS) y %APPDATA%\Claude\logs (Windows). En mcp.log están las conexiones y en mcp-server-SERVERNAME.log, el stderr del servidor. En macOS puedes seguirlos así:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Fuente: Connect to local MCP servers.

claude.ai y Desktop (conector). En Your connectors debe salir Connected. Si pone Connect o Reconnect, el inicio de sesión no terminó. Cada tool tiene que aparecer bajo Tool permissions. Para la prueba final, activa el conector en un chat desde + > Connectors, pide algo que use una tool y aprueba la llamada.

Claude Code. claude mcp list muestra ✔ Connected, ! Needs authentication o ✘ Failed to connect. Con /mcp ves el número de tools y acciones como Reconnect.

Antes de culpar al cliente, prueba el servidor por separado con el MCP Inspector:

npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http --method tools/list

Fuente: Claude: probar un conector.

Si el Inspector lista las tools y Claude no, el problema está entre Claude y tu servidor (red, autorización o ajustes del conector): mira la tabla de errores de abajo.

¿Por qué no aparece el servidor o falla la conexión?

En Claude Desktop con un servidor local, la guía oficial propone revisar cuatro causas:

• No has reiniciado del todo.
• El JSON está mal formado.
• Hay rutas relativas, y tienen que ser absolutas.
• El servidor no arranca. Para comprobarlo, ejecuta el comando a mano en una terminal.

En Windows, si ves un ENOENT con ${APPDATA}, añade en env el valor expandido de %APPDATA%.

En los conectores de claude.ai y Desktop, el mensaje que ves ya apunta a la causa:

Mensaje	Causas documentadas
«Couldn’t reach the MCP server»	El nombre resuelve a una IP privada, de loopback o CGNAT, o no tiene registro A. Un firewall, WAF o CDN bloquea a Anthropic. Falla el descubrimiento OAuth
«Authorization with the MCP server failed»	issuer que no coincide, audiencia mal validada, falta PKCE S256, errores de refresh, /token lento o una URL que redirige a otro host (Claude descarta Authorization al seguir la redirección)
«Unexpected error while invoking tool»	El conector está conectado y la tool devolvió un error: compara con el Inspector y con los registros del servidor

Fuente: Claude: solución de problemas de conectores.

El primero explica el caso del servidor que «works in Claude Code or curl but not claude.ai». Ocurre porque el conector sale desde la red de Anthropic. Estas son las comprobaciones de la documentación, que tienes que lanzar desde fuera de tu red:

dig +short your-server.example.com
curl -sI https://your-server.example.com/your-mcp-path
curl -i https://your-server.example.com/.well-known/oauth-protected-resource

Fuente: Claude: solución de problemas de conectores.

La segunda no debe dar un 3xx a otro host. En la tercera, si la URL tiene ruta, la añades al final (/.well-known/oauth-protected-resource/mcp).

¿Es seguro conectar un servidor MCP de terceros?

Depende de quién lo publica y de cuánto acceso le das. La guía oficial Local Server Security lo resume así: «treat a third-party local server as untrusted code with exactly the privileges you hand it — and hand it as few as possible». Estos son los criterios de la documentación de MCP y de Claude:

• Prefiere el remoto si existe. Un servidor que solo envuelve una API remota no gana nada ejecutándose en tu equipo.
• Comprueba la procedencia. Mira el publicador y el nombre exacto del paquete (cuidado con los nombres casi iguales), y fija la versión en lugar de usar latest. «A listing on a registry is not an endorsement».
• Permisos mínimos. Usa una credencial por servidor, con alcance mínimo y fuera de la configuración en texto plano. Dale la carpeta más estrecha posible y, si puedes, un contenedor o una VM.
• Lee las tools. Sus definiciones son entrada no fiable, porque pueden esconder instrucciones o cambiar después de que las apruebes. Mantén pocos servidores activos.
• En Claude, usa los permisos. Un conector personalizado conecta con servicios que Anthropic no ha verificado. Revisa los scopes, usa «Always allow» solo con servidores de confianza y bloquea las tools que no uses (Customize > Connectors > el conector > Blocked). Ni siquiera la etiqueta Verified del directorio es una auditoría: «It isn’t a security audit».

Un caso concreto es mcp-remote, un paquete de npm de terceros que hace de puente entre stdio y HTTP. Algunas guías, como las de Cloudflare, lo usan para llegar a un remoto desde claude_desktop_config.json. Tuvo un aviso crítico, CVE-2025-6514 (9 de julio de 2025), en las versiones desde la 0.0.5 hasta antes de la 0.1.16: «OS command injection via untrusted MCP server connections». Bastaba con conectarse a un servidor malicioso.

Si lo usas, fija una versión corregida, por ejemplo mcp-remote@0.14.3 (la última en npm, del 21 de septiembre de 2026), y no @latest. Mejor aún, usa el conector personalizado.

El artículo sobre seguridad en servidores MCP repasa los avisos de seguridad de los últimos meses.

¿Qué versión del protocolo habla cada cliente de Claude?

La especificación actual es la 2026-07-28, la que eliminó el handshake initialize y las sesiones. Cada cliente documenta algo distinto:

• Claude Code sí la documenta. Su runtime v2 usa el SDK de TypeScript 2.0, «which adds MCP protocol revision 2026-07-28», y pregunta a los servidores HTTP si la admiten. Según su changelog, desde la versión 2.1.292 (6 de octubre de 2026) también negocia 2026-07-28 por defecto con los servidores locales (stdio). Con MCP_PROTOCOL_NEGOTIATION=legacy vuelve al comportamiento anterior. Su página de MCP aún describe ese cambio como un despliegue gradual y no explica cómo ver qué versión se negoció.
• claude.ai y Claude Desktop: la documentación técnica de conectores no nombra ninguna revisión del protocolo. Solo cita las especificaciones de autorización que sigue (2025-03-26, 2025-06-18 y 2025-11-25). El 25 de septiembre de 2026, Anthropic escribió en su blog que «Claude supports the latest MCP spec, commonly referred to as MCP 2.0, which includes a stateless core». Ese apodo tiene su propio artículo: qué es «MCP 2.0».

La versión no se escribe en la configuración. La declara el cliente en cada petición, y un servidor puede atender a la vez la versión actual y las anteriores.

Lo que sí importa es el servidor. Los de referencia, como el Filesystem del ejemplo, dependen aún del SDK v1, cuya última revisión es la 2025-11-25, y su repositorio avisa de que no son «production-ready solutions».

¿Por dónde sigo?

La lección 12 del curso compara la configuración de cada cliente (Claude Code, Cursor, Gemini CLI, Codex y los conectores de Claude) y los mensajes que viajan al conectar. La lección 11 da el paso siguiente: un agente con Claude que orquesta varios servidores, con aprobación humana y auditoría. Las dos son del nivel Básico, gratuito con registro.

Si usas Cursor, la configuración equivalente está en servidor MCP en Cursor, y si algo no aparece, en cómo depurar un servidor MCP.