Cómo agregar un servidor MCP a Claude Code: comandos, alcances y soluciones

Lo habitual para conectar Claude Code con una herramienta es leer tres páginas de configuración distintas, copiar un comando que no es del todo correcto para tu sistema y preguntarte por qué no aparece nada. El proceso real es un comando y una verificación, siempre que sepas qué tipo de servidor estás agregando.

Esta guía te da los comandos para los tres tipos de servidor, explica los alcances que deciden quién recibe el servidor y cubre el inicio de sesión, la seguridad y las soluciones a lo que sale mal. Si MCP es nuevo para ti, empieza con Qué es MCP.

Qué necesitas

Conecta un servidor cuando notes que estás copiando datos de otra herramienta al chat. Una vez conectado, Claude puede leer de ese sistema y actuar en él directamente.

Tres tipos de servidor

El comando que uses depende de cómo se conecta el servidor contigo.

Servidor HTTP remoto

La forma básica es la misma para todos los servicios:

claude mcp add --transport http <name> <url>

Un ejemplo real conecta Notion:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Si el servidor necesita un token, pásalo como encabezado:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Servidor SSE remoto (obsoleto)

El método SSE está obsoleto, así que usa HTTP cuando el servicio lo ofrezca. Si un servicio solo tiene SSE, el comando usa otro transporte:

claude mcp add --transport sse asana https://mcp.asana.com/sse

Servidor stdio local

Un servidor stdio es un programa que se ejecuta en tu propio equipo, iniciado por Claude Code. La forma básica lleva un doble guion, y todo lo que va después es el comando que inicia el servidor:

claude mcp add [options] <name> -- <command> [args...]

Un ejemplo que agrega un servidor de Airtable con una clave de API:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Comprueba que funcionó

Después de agregar un servidor, revísalo desde tu terminal o dentro de Claude Code.

$ claude mcp list$ claude mcp get notion$ claude mcp remove notion

Dentro de una sesión, escribe /mcp para ver el estado de cada servidor. Verás uno de tres estados: conectado, necesita autenticación o error al conectar.

Inicia sesión con OAuth

Muchos servidores en la nube usan OAuth 2.0, el flujo de "inicia sesión con tu cuenta". El camino más simple tiene dos pasos.

Desde la terminal también puedes ejecutar claude mcp login <name> y claude mcp logout <name>. Los tokens se guardan de forma segura y se renuevan automáticamente. Para revocar el acceso, usa Clear authentication (borrar autenticación) en el menú de /mcp.

Alcances: quién recibe el servidor

Al agregar un servidor, eliges su alcance. El alcance decide qué proyectos lo ven y si tu equipo lo comparte.

Elige uno con la opción --scope:

# Project scope: shared with your team
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# User scope: available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Un servidor con alcance de proyecto escribe un archivo .mcp.json en la raíz de tu proyecto, que subes al repositorio para que todos tengan la misma conexión:

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

Si el mismo nombre de servidor aparece en más de un alcance, Claude Code se conecta una sola vez, con la definición de la fuente de mayor precedencia: primero local, luego proyecto y después usuario.

Cuando abres un proyecto que tiene un .mcp.json de otra persona, Claude Code pide tu aprobación antes de usar sus servidores en una sesión interactiva. Para restablecer esas decisiones de aprobación, ejecuta claude mcp reset-project-choices.

Servidores populares que puedes agregar hoy

Estos ejemplos vienen de la documentación oficial. Lee siempre la página del propio servicio para ver la dirección vigente.

En la base de datos, fíjate en el nombre de usuario: readonly. Dale a Claude una cuenta de base de datos que solo pueda leer. Esa sola decisión evita el error más costoso que podrías cometer.

También puedes explorar los conectores revisados en el directorio de Anthropic, en claude.ai/directory. Y si agregaste un conector en claude.ai, ya está disponible en Claude Code cuando inicias sesión con tu cuenta de Claude.

Mantente seguro

Un servidor MCP le da a Claude acceso a un sistema, y algunos servidores traen contenido de fuera, como páginas web o tickets escritos por desconocidos.

Ese último punto se relaciona con cuánto hace Claude sin preguntar. Consulta Modos de permisos de Claude Code y modo plan, explicados para decidirlo.

Dentro de Claude Tutorial

Confiar en una herramienta es una decisión, no un valor predeterminado

Juzgar qué sistemas merecen acceso, y para qué acciones, es una habilidad que sirve mucho más allá del código, y la app la practica con escenarios reales.

Muy pronto

Descárgalo en elApp Store

DISPONIBLE ENGoogle Play

Límites y ajustes

Dos límites ayudan a explicar comportamientos que de otro modo parecen raros.

• Resultados grandes. Claude Code muestra una advertencia cuando la salida de una herramienta pasa de 10,000 tokens, y limita la salida a 25,000 tokens de forma predeterminada. Para subir el límite, define la variable MAX_MCP_OUTPUT_TOKENS, por ejemplo MAX_MCP_OUTPUT_TOKENS=50000.
• Servidores lentos. Para cambiar cuánto espera Claude Code a que un servidor inicie, define MCP_TIMEOUT. Por ejemplo, MCP_TIMEOUT=10000 claude permite diez segundos.

La búsqueda de herramientas viene activada de forma predeterminada, para que tu contexto no se llene de golpe con la descripción de cada herramienta. Ejecuta /context para ver qué está ocupando espacio.

Cuando no funciona

Cuando nada de eso encaje, pídele ayuda a Claude Code: pega el error y pregunta qué significa. Ejecutar /doctor también revisa tu configuración.

Preguntas frecuentes

¿Cómo agrego un servidor MCP a Claude Code?

Ejecuta claude mcp add --transport http <name> <url> para un servidor remoto, o claude mcp add <name> -- <command> para uno local. Luego ejecuta /mcp dentro de Claude Code para revisar su estado e iniciar sesión.

¿Dónde guarda Claude Code los servidores MCP?

Los servidores de alcance local y de usuario se guardan en ~/.claude.json. Los de alcance de proyecto se guardan en un archivo .mcp.json en la raíz de tu proyecto, que puedes subir al repositorio.

¿Qué diferencia hay entre el alcance local, el de proyecto y el de usuario?

El local aplica al proyecto actual y solo a ti. El de proyecto aplica al proyecto actual y se comparte con tu equipo. El de usuario aplica a todos tus proyectos y solo a ti.

¿Cómo elimino un servidor MCP?

Ejecuta claude mcp remove <name>. Para cerrar sesión en un servidor sin eliminarlo, usa claude mcp logout <name>.

¿Qué significa el doble guion en claude mcp add?

Separa las opciones propias de Claude Code del comando que inicia el servidor. Todo lo que va después se pasa al servidor sin tocarlo.

¿Los servidores MCP son seguros?

Solo son tan seguros como los servidores que eliges y el acceso que das. Usa servidores de confianza, cuentas de base de datos de solo lectura y un modo de permisos en el que puedas ver lo que hace Claude.

¿Puedo usar mis conectores de claude.ai en Claude Code?

Sí. Los conectores que agregas en claude.ai están disponibles en Claude Code, en la terminal y en las sesiones en la nube, cuando inicias sesión con tu cuenta de Claude.

Tu lista de verificación de MCP en Claude Code

Sigue leyendo

• Qué es MCP: el Model Context Protocol explicado fácil para la idea que hay detrás.
• Cómo agregar conectores en Claude: directorio, URL personalizada y seguridad para lo mismo en las apps de Claude.
• Buenas prácticas de Claude Code: hábitos que dan mejores resultados para trabajar bien una vez conectadas las herramientas.
• CLAUDE.md explicado: enséñale tu proyecto a Claude Code una sola vez para decirle a Claude cómo usar las herramientas conectadas en tu proyecto.