Claude Code · MCP · Integraciones

Claude Code MCP: qué es, cómo configurarlo y conectar herramientas externas

Model Context Protocol (MCP) permite conectar Claude Code con herramientas, bases de datos, APIs, GitHub, navegadores, sistemas internos y servicios externos. En lugar de copiar información manualmente dentro del chat, Claude puede consultar y utilizar directamente las herramientas expuestas por un servidor MCP.

Añadir servidor MCP Ver ejemplos
HTTP stdio .mcp.json OAuth
Respuesta rápida

¿Qué es MCP en Claude Code?

MCP es un estándar abierto que permite conectar Claude Code con herramientas y fuentes de datos externas. Un servidor MCP puede exponer herramientas, recursos y prompts para que Claude pueda consultar GitHub, bases de datos, sistemas internos, documentación, navegadores u otras APIs. Para servidores remotos, Claude Code recomienda actualmente utilizar transporte HTTP. Para herramientas que se ejecutan en tu propio equipo, normalmente se utiliza stdio.

Capacidades

Qué puede hacer Claude Code mediante MCP

MCP permite que Claude deje de trabajar únicamente con información local del repositorio.

GIT

GitHub

Leer issues, revisar pull requests, consultar repositorios y trabajar con GitHub.

DB

Bases de datos

Consultar PostgreSQL, MySQL u otras fuentes de datos.

WEB

Navegadores

Automatizar navegación, testing e interacción web mediante servidores compatibles.

API

APIs

Conectar servicios propios o plataformas de terceros.

DOC

Documentación

Consultar recursos externos sin copiarlos manualmente al chat.

AUTO

Workflows

Combinar varias herramientas dentro de una misma tarea agentic.

Publicidad
Cómo funciona

Claude → MCP → herramienta externa

MCP actúa como una capa estandarizada entre Claude Code y los sistemas que quieres integrar.

01 · DISCOVER

Descubre herramientas

Claude conoce las capacidades disponibles en los servidores MCP.

02 · CALL

Ejecuta una herramienta

Claude selecciona la integración necesaria según la tarea.

03 · RESULT

Utiliza el resultado

La respuesta del servidor vuelve a Claude para continuar el workflow.

Publicidad
Conceptos

MCP vs Skills vs Subagents

Son extensiones diferentes del ecosistema de Claude Code.

Herramienta Función principal
CLAUDE.md Reglas persistentes del proyecto
Skills Procedimientos y conocimiento reutilizable
Subagents Delegar tareas a contextos especializados
MCP Conectar herramientas y sistemas externos
Hooks Automatizar acciones alrededor de eventos
Publicidad
Transportes

HTTP, stdio, SSE y WebSocket

El transporte determina cómo Claude Code se comunica con el servidor MCP.

Transporte Uso Estado
http Servidores remotos y cloud Recomendado
stdio Procesos que se ejecutan localmente Recomendado local
sse Servidores antiguos basados en Server-Sent Events Deprecado cuando hay HTTP
ws Conexiones WebSocket bidireccionales Disponible vía configuración JSON
Regla práctica

Para un servicio alojado en Internet, empieza por HTTP. Para un script o programa que se ejecuta en tu computador, utiliza stdio.

HTTP

Cómo añadir un servidor MCP remoto

HTTP es actualmente la opción recomendada para servidores MCP remotos.

Sintaxis

Agregar servidor HTTP

claude mcp add --transport http nombre https://mcp.example.com/mcp
Ejemplo

Conectar Notion

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

Añadir un servidor con Bearer Token

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"
No publiques tokens en Git

Para configuraciones compartidas, utiliza variables de entorno en lugar de introducir secretos directamente dentro de .mcp.json.

stdio

Agregar un servidor MCP local

Los servidores stdio funcionan como procesos que Claude Code inicia directamente en tu computador.

Sintaxis 
claude mcp add --transport stdio my-server -- npx -y my-mcp-server
El doble guion — es importante

Todo lo situado después de -- se entrega directamente al proceso que ejecutará el servidor MCP.

Ejemplo mental

Las opciones anteriores a -- pertenecen a Claude Code. Las opciones posteriores pertenecen al servidor MCP.

Variables

Pasar variables de entorno a un servidor local

claude mcp add \
  --env API_KEY=YOUR_KEY \
  --transport stdio \
  my-server \
  -- npx -y my-mcp-server
Proyecto

CLAUDE_PROJECT_DIR dentro de servidores stdio

Claude Code proporciona automáticamente la ruta raíz del proyecto al proceso MCP local.

Environment

Variable disponible

CLAUDE_PROJECT_DIR
Muy útil para servidores propios

Tu servidor puede utilizar esa variable para encontrar archivos del proyecto sin asumir cuál es el working directory.

Scopes

Local, project y user

El scope determina dónde queda guardado el servidor y quién puede utilizarlo.

Scope Disponible en Compartido Ubicación
local Proyecto actual No ~/.claude.json
project Proyecto actual Sí .mcp.json
user Todos tus proyectos No ~/.claude.json
Local es el valor predeterminado

Si no especificas --scope, Claude Code guarda normalmente el servidor como configuración local para ese proyecto.

Equipo

Compartir servidores mediante .mcp.json

Project scope permite versionar la configuración MCP junto al repositorio.

Project scope 
claude mcp add \
  --transport http \
  --scope project \
  docs \
  https://mcp.example.com/mcp
.mcp.json 
{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}
Seguridad

Los servidores compartidos requieren aprobación

Un repositorio que acabas de clonar no debería poder ejecutar automáticamente cualquier servidor MCP.

Workspace trust

Claude Code pide aprobación

Cuando existe un servidor dentro de .mcp.json, Claude Code puede mostrarlo como pendiente hasta que confíes explícitamente en el workspace y en la configuración. 

claude mcp reset-project-choices
Revisa .mcp.json antes de aprobar

Especialmente cuando el repositorio procede de terceros.

Precedencia

Qué ocurre si el mismo servidor existe en varios scopes

1

Local

Mayor precedencia entre los scopes normales.

2

Project

Configuración compartida mediante .mcp.json.

3

User

Configuración personal para todos los proyectos.

4

Plugins y Connectors

Se utilizan cuando no existe una definición con mayor precedencia.

Las entradas no se mezclan

Cuando el mismo nombre aparece en varios scopes, Claude utiliza la definición completa de mayor precedencia, no una combinación de sus campos.

Secretos

Variables de entorno dentro de .mcp.json

Puedes compartir la configuración sin guardar claves privadas directamente en Git. 

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}
También admite valores por defecto

La sintaxis ${VAR:-default} utiliza el valor de la variable cuando existe y el fallback cuando no.

Publicidad
Administración

Comandos para administrar servidores MCP

Acción Comando
Listar servidores claude mcp list
Ver un servidor claude mcp get nombre
Eliminar servidor claude mcp remove nombre
Panel dentro de Claude /mcp
Login OAuth claude mcp login nombre
Logout OAuth claude mcp logout nombre
Estado

Cómo saber si un servidor MCP funciona

claude mcp list
Estado Significado
Connected Servidor disponible
Needs authentication Debes completar autenticación
Failed to connect Error de conexión o configuración
Pending approval Servidor del proyecto pendiente de aprobación
Disabled Desactivado para el proyecto
OAuth

Autenticar servidores MCP remotos

Claude Code soporta OAuth 2.0 para servicios que requieren autorización del usuario.

Interactivo

Desde Claude Code

/mcp
CLI

Autenticar desde terminal

claude mcp login sentry
Los tokens se refrescan automáticamente

Cuando el servidor soporta OAuth correctamente, Claude Code guarda la autenticación y puede renovar el access token cuando corresponda.

SSH

Autenticar MCP cuando no tienes navegador local

claude mcp login sentry --no-browser
Claude mostrará una URL

Puedes abrirla en otro navegador y después pegar la URL completa de redirección en la terminal.

GitHub

Ejemplo: conectar Claude Code con GitHub

El ejemplo oficial utiliza el servidor remoto de GitHub y un token de acceso. 

claude mcp add \
  --transport http \
  github \
  https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"
Utiliza un token con mínimo privilegio

Concede únicamente acceso a los repositorios y operaciones que realmente necesites.

Prompt 
Revisa el PR #456.

Busca:
- bugs
- problemas de seguridad
- regresiones
- falta de tests

No publiques comentarios todavía.
Primero muéstrame el informe.
Base de datos

Ejemplo: consultar PostgreSQL con MCP

Claude puede consultar una base de datos relacional mediante un servidor MCP apropiado. 

claude mcp add \
  --transport stdio \
  db \
  -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:password@db.example.com:5432/analytics"
Usa un usuario read-only

La propia documentación de Anthropic recomienda utilizar credenciales de solo lectura cuando Claude necesita consultar datos pero no modificarlos. 

Muéstrame el esquema de la tabla orders.

Después calcula:
- número de órdenes
- ticket promedio
- ingresos del mes

No realices ninguna modificación.
MCP Resources

Referenciar recursos MCP con @

MCP no expone únicamente herramientas. Los servidores también pueden proporcionar recursos.

@

Autocompletado de recursos

Escribe @ en el prompt para ver recursos disponibles junto a archivos locales. 

Analiza @github:issue://123
y propón cómo solucionarlo.
Múltiples recursos 
Compara @postgres:schema://users
con @docs:file://database/user-model
Contexto

Tool Search evita cargar todas las herramientas MCP

Un servidor puede exponer muchas herramientas, pero Claude Code no necesita cargar todas sus definiciones desde el comienzo.

Tool Search

Descubrimiento bajo demanda

Claude Code mantiene únicamente información suficiente para descubrir las herramientas y carga sus definiciones cuando realmente resultan relevantes.

Está activado por defecto

Esto permite tener múltiples servidores MCP sin consumir automáticamente una gran parte de la ventana de contexto.

Tokens

Qué ocurre cuando una herramienta MCP devuelve demasiado contenido

Valor Comportamiento
10.000 tokens Claude Code muestra una advertencia
25.000 tokens Límite predeterminado habitual
Resultado excesivo Puede guardarse en archivo y referenciarse desde el chat
Configuración 
export MAX_MCP_OUTPUT_TOKENS=50000
claude
Mejor solución: reducir resultados

Siempre que sea posible, pagina respuestas, filtra datos y devuelve únicamente la información que Claude necesita.

Publicidad
Subagents

Combinar MCP con Claude Code Subagents

No todos los servidores MCP tienen que estar disponibles en la conversación principal. 

---
name: database-analyst
description: Analiza datos mediante el servidor MCP de base de datos
model: sonnet
mcpServers:
  - db
---

Utiliza el servidor de base de datos
para responder consultas analíticas.

No modifiques datos.
Reduce ruido en el contexto principal

Puedes entregar el servidor MCP únicamente al subagente especializado que realmente necesita utilizarlo.

Claude Code Subagents →
Skills

Combinar Skills y MCP

MCP aporta las herramientas. Skills pueden explicar cómo utilizarlas.

Ejemplo

Skill de análisis de ventas

Un Skill podría definir métricas, reglas de negocio y formato del informe, mientras el servidor MCP proporciona acceso a PostgreSQL.

Separación limpia

MCP: capacidad técnica.
Skill: procedimiento y conocimiento.

Claude Code Skills →
Seguridad

MCP amplía lo que Claude puede hacer

Por eso cada servidor debe considerarse una extensión de la superficie de acceso de Claude Code.

01

Instala servidores únicamente de fuentes en las que confíes.

02

Utiliza credenciales con mínimo privilegio.

03

Prefiere usuarios de base de datos read-only para análisis.

04

No almacenes API keys directamente en repositorios.

05

Revisa .mcp.json antes de aprobar un proyecto clonado.

06

Limita OAuth scopes a las capacidades necesarias.

07

Evita conectar sistemas productivos con permisos de escritura sin controles.

Prompt injection

Un servidor MCP puede introducir contenido externo

Esto es importante cuando el servidor obtiene información de Internet, documentos, issues o mensajes controlados por terceros.

Contenido externo no equivale a instrucciones confiables

Un issue, página web o documento puede contener texto diseñado para manipular el comportamiento de un agente.

Verifica antes de conectar

Anthropic recomienda confiar únicamente en servidores MCP y fuentes cuyo comportamiento comprendas.

OAuth scopes

Limitar los permisos solicitados por OAuth

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}
Evita permisos excesivos

Si solo necesitas leer información, no solicites permisos administrativos o de escritura innecesarios.

Enterprise

Tokens dinámicos con headersHelper

Para SSO, Kerberos o credenciales de corta duración, Claude Code puede generar headers al momento de conectarse. 

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

Servidor MCP no conecta

01

Ejecuta claude mcp list y revisa el estado.

02

Ejecuta claude mcp get nombre para obtener detalles.

03

Si necesita OAuth, utiliza /mcp o claude mcp login.

04

Comprueba URL, transport y credenciales.

05

Revisa variables de entorno ausentes.

06

Elimina espacios ocultos al principio o final de tokens y URLs.

07

Si es stdio, prueba manualmente el comando que inicia el servidor.

08

Si es .mcp.json, comprueba que el servidor haya sido aprobado.

Error frecuente

Una URL dentro de .mcp.json necesita type

Incorrecto 
{
  "url": "https://mcp.example.com/mcp"
}
Correcto 
{
  "type": "http",
  "url": "https://mcp.example.com/mcp"
}
Sin type Claude puede interpretarlo como stdio

Añade siempre el transporte cuando configures manualmente una URL.

Avanzado

Claude Code también puede funcionar como servidor MCP

Otras aplicaciones compatibles con MCP pueden utilizar las herramientas de Claude Code. 

claude mcp serve
Es un servidor stdio

El comando queda esperando comunicación mediante stdin y stdout.

Checklist

Antes de conectar un servidor MCP

01

Verifica quién mantiene el servidor.

02

Revisa qué herramientas expone.

03

Comprueba qué datos podrá leer.

04

Comprueba qué acciones podrá ejecutar.

05

Utiliza credenciales limitadas.

06

Evita secretos dentro de archivos versionados.

07

Prueba primero en desarrollo o staging.

08

Confirma la conexión mediante /mcp.

Publicidad
Decisión

Cuándo merece la pena utilizar MCP

Información externa Copias continuamente datos desde otra herramienta
MCP
Base de datos Claude necesita consultar datos reales
MCP
GitHub Trabajas con PRs e issues
MCP
Procedimiento Solo necesitas guardar instrucciones
Skill
Delegación Necesitas otro contexto de trabajo
Subagent
Automatización Necesitas reaccionar a una herramienta
Hook
Fuentes oficiales

Documentación oficial de MCP para Claude Code

MCP cambia rápidamente, especialmente en transportes, OAuth, tool search y seguridad.

Anthropic

Subagents

Cómo proporcionar servidores MCP únicamente a agentes especializados.

Ver Subagents →
Publicidad
Cluster Claude Code

Guías relacionadas

Publicidad
Preguntas frecuentes

FAQ sobre Claude Code MCP

Respuestas sobre servidores, transportes, scopes, autenticación, recursos y seguridad.

Model Context Protocol es un estándar abierto que permite conectar Claude Code con herramientas, APIs, bases de datos y fuentes externas de información.

Puedes utilizar claude mcp add. Para un servidor remoto HTTP, por ejemplo: claude mcp add --transport http nombre URL.

HTTP es actualmente la opción recomendada para servidores remotos. Para procesos que se ejecutan localmente, normalmente se utiliza stdio. SSE está deprecado cuando existe una alternativa HTTP.

Es el archivo utilizado para almacenar servidores MCP con scope de proyecto. Puede versionarse para que todo el equipo utilice la misma configuración.

Local se aplica únicamente al proyecto y permanece privado para tu usuario. Project se guarda en .mcp.json y puede compartirse mediante Git. User está disponible para todos tus proyectos en esa máquina.

Sí. Claude Code soporta OAuth 2.0 para servidores MCP remotos. Puedes autenticarte desde /mcp o mediante claude mcp login nombre.

Sí. GitHub dispone de integración MCP que permite consultar issues, pull requests y otras operaciones, dependiendo de los permisos otorgados.

Sí. Puedes utilizar un servidor MCP que exponga PostgreSQL, MySQL u otra base de datos. Para análisis es recomendable utilizar credenciales de solo lectura.

Son contenidos expuestos por un servidor MCP. Claude Code puede mostrarlos junto a archivos cuando escribes @ y permite referenciarlos directamente desde el prompt.

Depende del servidor y de los permisos otorgados. Debes utilizar servidores confiables, limitar credenciales, revisar configuraciones compartidas y considerar riesgos como prompt injection desde contenido externo.

Publicidad
Siguiente guía

Extiende Claude Code con Plugins

Ya sabes cómo conectar Claude Code con herramientas externas mediante MCP. El siguiente paso es aprender a empaquetar Skills, Subagents, Hooks y servidores MCP dentro de Plugins reutilizables y distribuibles.

Claude Code Plugins →
Carrito de compra
Scroll al inicio