Conectar Claude Code a herramientas mediante MCP

​

Qué puede hacer con MCP

• Implemente características desde rastreadores de problemas: “Agregue la característica descrita en el problema JIRA ENG-4521 y cree un PR en GitHub.”
• Analice datos de monitoreo: “Verifique Sentry y Statsig para verificar el uso de la característica descrita en ENG-4521.”
• Consulte bases de datos: “Encuentre correos electrónicos de 10 usuarios aleatorios que utilizaron la característica ENG-4521, basándose en nuestra base de datos PostgreSQL.”
• Integre diseños: “Actualice nuestra plantilla de correo electrónico estándar basándose en los nuevos diseños de Figma que se publicaron en Slack”
• Automatice flujos de trabajo: “Cree borradores de Gmail invitando a estos 10 usuarios a una sesión de retroalimentación sobre la nueva característica.”
• Reaccione a eventos externos: Un servidor MCP también puede actuar como un canal que envía mensajes a su sesión, para que Claude reaccione a mensajes de Telegram, chats de Discord o eventos de webhook mientras está fuera.

​

Servidores MCP populares

​

Instalación de servidores MCP

​

Opción 1: Agregar un servidor HTTP remoto

# Sintaxis básica
claude mcp add --transport http <name> <url>

# Ejemplo real: Conectar a Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

​

Opción 2: Agregar un servidor SSE remoto

# Sintaxis básica
claude mcp add --transport sse <name> <url>

# Ejemplo real: Conectar a Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Ejemplo con encabezado de autenticación
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

​

Opción 3: Agregar un servidor stdio local

# Sintaxis básica
claude mcp add [options] <name> -- <command> [args...]

# Ejemplo real: Agregar servidor Airtable
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

​

Gestión de sus servidores

# Listar todos los servidores configurados
claude mcp list

# Obtener detalles para un servidor específico
claude mcp get github

# Eliminar un servidor
claude mcp remove github

# (dentro de Claude Code) Verificar estado del servidor
/mcp

​

Actualizaciones dinámicas de herramientas

​

Mensajes push con canales

# Esto crea command="cmd" que Windows puede ejecutar
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

​

Servidores MCP proporcionados por plugins

• Los plugins definen servidores MCP en .mcp.json en la raíz del plugin o en línea en plugin.json
• Cuando un plugin está habilitado, sus servidores MCP se inician automáticamente
• Las herramientas MCP del plugin aparecen junto a las herramientas MCP configuradas manualmente
• Los servidores de plugins se gestionan a través de la instalación de plugins (no mediante comandos /mcp)

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

• Ciclo de vida automático: Al iniciar la sesión, los servidores de los plugins habilitados se conectan automáticamente. Si habilita o deshabilita un plugin durante una sesión, ejecute /reload-plugins para conectar o desconectar sus servidores MCP
• Variables de entorno: Use ${CLAUDE_PLUGIN_ROOT} para archivos agrupados en el plugin y ${CLAUDE_PLUGIN_DATA} para estado persistente que sobrevive a las actualizaciones de plugins
• Acceso a variables de entorno del usuario: Acceso a las mismas variables de entorno que los servidores configurados manualmente
• Múltiples tipos de transporte: Soporte para transportes stdio, SSE e HTTP (el soporte de transporte puede variar según el servidor)

# Dentro de Claude Code, vea todos los servidores MCP incluyendo los de plugins
/mcp

• Distribución agrupada: Herramientas y servidores empaquetados juntos
• Configuración automática: No se necesita configuración manual de MCP
• Consistencia del equipo: Todos obtienen las mismas herramientas cuando se instala el plugin

​

Alcances de instalación de MCP

​

Alcance local

# Agregar un servidor con alcance local (predeterminado)
claude mcp add --transport http stripe https://mcp.stripe.com

# Especificar explícitamente alcance local
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

​

Alcance de proyecto

# Agregar un servidor con alcance de proyecto
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

​

Alcance de usuario

# Agregar un servidor de usuario
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

​

Elegir el alcance correcto

• Alcance local: Servidores personales, configuraciones experimentales o credenciales sensibles específicas de un proyecto
• Alcance de proyecto: Servidores compartidos por el equipo, herramientas específicas del proyecto o servicios requeridos para la colaboración
• Alcance de usuario: Utilidades personales necesarias en múltiples proyectos, herramientas de desarrollo o servicios frecuentemente utilizados

​

Jerarquía de alcance y precedencia

​

Expansión de variables de entorno en .mcp.json

• ${VAR} - Se expande al valor de la variable de entorno VAR
• ${VAR:-default} - Se expande a VAR si está establecida, de lo contrario usa default

• command - La ruta del ejecutable del servidor
• args - Argumentos de línea de comandos
• env - Variables de entorno pasadas al servidor
• url - Para tipos de servidor HTTP
• headers - Para autenticación de servidor HTTP

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

​

Ejemplos prácticos

​

Ejemplo: Monitorear errores con Sentry

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

/mcp

¿Cuáles son los errores más comunes en las últimas 24 horas?

Muéstrame el seguimiento de pila para el error ID abc123

¿Qué despliegue introdujo estos nuevos errores?

​

Ejemplo: Conectar a GitHub para revisiones de código

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

/mcp

Revise el PR #456 y sugiera mejoras

Cree un nuevo problema para el error que acabamos de encontrar

Muéstrame todos los PR abiertos asignados a mí

​

Ejemplo: Consultar su base de datos PostgreSQL

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

¿Cuál es nuestro ingreso total este mes?

Muéstrame el esquema para la tabla de pedidos

Encuentre clientes que no han realizado una compra en 90 días

​

Autenticarse con servidores MCP remotos

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

/mcp

​

Usar un puerto de devolución de llamada OAuth fijo

# Puerto de devolución de llamada fijo con registro dinámico de clientes
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

​

Usar credenciales OAuth preconfiguradas

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

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

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

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

​

Anular el descubrimiento de metadatos de OAuth

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

​

Usar encabezados dinámicos para autenticación personalizada

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

• El comando debe escribir un objeto JSON de pares clave-valor de cadena en stdout
• El comando se ejecuta en un shell con un tiempo de espera de 10 segundos
• Los encabezados dinámicos anulan cualquier headers estático con el mismo nombre

​

Agregar servidores MCP desde configuración JSON

# Sintaxis básica
claude mcp add-json <name> '<json>'

# Ejemplo: Agregar un servidor HTTP con configuración JSON
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Ejemplo: Agregar un servidor stdio con configuración JSON
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Ejemplo: Agregar un servidor HTTP con credenciales OAuth preconfiguradas
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

claude mcp get weather-api

​

Importar servidores MCP desde Claude Desktop

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

claude mcp list 

​

Usar servidores MCP desde Claude.ai

/mcp

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

​

Usar Claude Code como servidor MCP

# Iniciar Claude como servidor MCP stdio
claude mcp serve

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

which claude

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

​

Límites de salida de MCP y advertencias

• Umbral de advertencia de salida: Claude Code muestra una advertencia cuando la salida de cualquier herramienta MCP excede 10,000 tokens
• Límite configurable: Puede ajustar los tokens de salida MCP máximos permitidos usando la variable de entorno MAX_MCP_OUTPUT_TOKENS
• Límite predeterminado: El máximo predeterminado es 25,000 tokens

# Establecer un límite más alto para salidas de herramientas MCP
export MAX_MCP_OUTPUT_TOKENS=50000
claude

• Consultan grandes conjuntos de datos o bases de datos
• Generan reportes o documentación detallados
• Procesan archivos de registro extensos o información de depuración

​

Responder a solicitudes de elicitación de MCP

• Modo de formulario: Claude Code muestra un diálogo con campos de formulario definidos por el servidor (por ejemplo, un indicador de nombre de usuario y contraseña). Complete los campos y envíe.
• Modo de URL: Claude Code abre una URL del navegador para autenticación o aprobación. Complete el flujo en el navegador, luego confirme en la CLI.

​

Usar recursos MCP

​

Referenciar recursos MCP

¿Puede analizar @github:issue://123 y sugerir una solución?

Por favor revise la documentación de API en @docs:file://api/authentication

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

​

Escalar con MCP Tool Search

​

Cómo funciona

1. Las herramientas MCP se difieren en lugar de cargarse en el contexto de antemano
2. Claude usa una herramienta de búsqueda para descubrir herramientas MCP relevantes cuando sea necesario
3. Solo se cargan en el contexto las herramientas que Claude realmente necesita
4. Las herramientas MCP continúan funcionando exactamente como antes desde su perspectiva

​

Para autores de servidores MCP

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

​

Configurar búsqueda de herramientas

# Usar un umbral personalizado del 5%
ENABLE_TOOL_SEARCH=auto:5 claude

# Desactivar búsqueda de herramientas completamente
ENABLE_TOOL_SEARCH=false claude

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

​

Usar indicaciones MCP como comandos

​

Ejecutar indicaciones MCP

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug en flujo de inicio de sesión" high

​

Configuración MCP gestionada

1. Control exclusivo con managed-mcp.json: Implemente un conjunto fijo de servidores MCP que los usuarios no pueden modificar ni extender
2. Control basado en políticas con listas de permitidos/bloqueados: Permita que los usuarios agreguen sus propios servidores, pero restrinja cuáles están permitidos

• Controlar a qué servidores MCP pueden acceder los empleados: Implemente un conjunto estandarizado de servidores MCP aprobados en toda la organización
• Prevenir servidores MCP no autorizados: Restrinja a los usuarios de agregar servidores MCP no aprobados
• Desactivar MCP completamente: Elimine completamente la funcionalidad MCP si es necesario

​

Opción 1: Control exclusivo con managed-mcp.json

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux y WSL: /etc/claude-code/managed-mcp.json
• Windows: C:\Program Files\ClaudeCode\managed-mcp.json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

​

Opción 2: Control basado en políticas con listas de permitidos y bloqueados

​

Opciones de restricción

1. Por nombre de servidor (serverName): Coincide con el nombre configurado del servidor
2. Por comando (serverCommand): Coincide con el comando exacto y los argumentos utilizados para iniciar servidores stdio
3. Por patrón de URL (serverUrl): Coincide con URLs de servidor remoto con soporte de comodín

​

Configuración de ejemplo

{
  "allowedMcpServers": [
    // Permitir por nombre de servidor
    { "serverName": "github" },
    { "serverName": "sentry" },

    // Permitir por comando exacto (para servidores stdio)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // Permitir por patrón de URL (para servidores remotos)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // Bloquear por nombre de servidor
    { "serverName": "dangerous-server" },

    // Bloquear por comando exacto (para servidores stdio)
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // Bloquear por patrón de URL (para servidores remotos)
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

​

Cómo funcionan las restricciones basadas en comandos

• Los arrays de comandos deben coincidir exactamente - tanto el comando como todos los argumentos en el orden correcto
• Ejemplo: ["npx", "-y", "server"] NO coincidirá con ["npx", "server"] o ["npx", "-y", "server", "--flag"]

• Cuando la lista de permitidos contiene cualquier entrada serverCommand, los servidores stdio deben coincidir con uno de esos comandos
• Los servidores stdio no pueden pasar solo por nombre cuando hay restricciones de comando presentes
• Esto asegura que los administradores puedan aplicar qué comandos están permitidos ejecutarse

• Los servidores remotos (HTTP, SSE, WebSocket) usan coincidencia basada en URL cuando existen entradas serverUrl en la lista de permitidos
• Si no existen entradas de URL, los servidores remotos recurren a coincidencia basada en nombre
• Las restricciones de comando no se aplican a servidores remotos

​

Cómo funcionan las restricciones basadas en URL

• https://mcp.company.com/* - Permitir todas las rutas en un dominio específico
• https://*.example.com/* - Permitir cualquier subdominio de example.com
• http://localhost:*/* - Permitir cualquier puerto en localhost

• Cuando la lista de permitidos contiene cualquier entrada serverUrl, los servidores remotos deben coincidir con uno de esos patrones de URL
• Los servidores remotos no pueden pasar solo por nombre cuando hay restricciones de URL presentes
• Esto asegura que los administradores puedan aplicar qué puntos finales remotos están permitidos

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ]
}

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-tool" }
  ]
}

​

Comportamiento de la lista de permitidos (allowedMcpServers)

• undefined (predeterminado): Sin restricciones - los usuarios pueden configurar cualquier servidor MCP
• Array vacío []: Bloqueo completo - los usuarios no pueden configurar ningún servidor MCP
• Lista de entradas: Los usuarios solo pueden configurar servidores que coincidan por nombre, comando o patrón de URL

​

Comportamiento de la lista de bloqueados (deniedMcpServers)

• undefined (predeterminado): Ningún servidor está bloqueado
• Array vacío []: Ningún servidor está bloqueado
• Lista de entradas: Los servidores especificados están explícitamente bloqueados en todos los alcances

​

Notas importantes

• La Opción 1 y la Opción 2 se pueden combinar: Si existe managed-mcp.json, tiene control exclusivo y los usuarios no pueden agregar servidores. Las listas de permitidos/bloqueados aún se aplican a los servidores gestionados mismos.
• La lista de bloqueados tiene precedencia absoluta: Si un servidor coincide con una entrada de lista de bloqueados (por nombre, comando o URL), será bloqueado incluso si está en la lista de permitidos
• Las restricciones basadas en nombre, comando y URL funcionan juntas: un servidor pasa si coincide con cualquiera de una entrada de nombre, una entrada de comando o un patrón de URL (a menos que esté bloqueado por lista de bloqueados)