MCP servers: cómo configurar en Claude Code

Sin MCP, Claude Code solo puede leer archivos y ejecutar comandos de terminal. Con MCP, puede interactuar con GitHub, bases de datos, APIs, navegadores, servicios cloud y más.

Cómo funciona

La arquitectura es sencilla:

1. Configuras un servidor MCP en tu settings.json
2. Claude Code inicia el servidor como un proceso hijo
3. El servidor anuncia sus herramientas disponibles (list tools)
4. Claude Code usa las herramientas cuando tu tarea lo requiere
5. El servidor ejecuta la acción y devuelve el resultado

Todo ocurre de forma transparente. No tienes que invocar herramientas manualmente: Claude Code decide cuándo usarlas basándose en tu petición.

El protocolo MCP usa comunicación stdio (standard input/output) por defecto. El servidor es un proceso local que se ejecuta en tu máquina. No hay conexiones de red adicionales (excepto las que el propio servidor haga a APIs externas como GitHub o Supabase). Esto significa que los datos fluyen: tu prompt → Claude Code → proceso MCP local → API externa. Claude Code no envía tus datos a ningún sitio adicional por el hecho de usar MCP.

Configuración paso a paso

Los MCP servers se configuran en .claude/settings.json (por proyecto) o ~/.claude/settings.json (global):

// .claude/settings.json
{
 "mcpServers": {
 "nombre-del-servidor": {
 "command": "comando-para-ejecutar",
 "args": ["argumento1", "argumento2"],
 "env": {
 "API_KEY": "tu-api-key"
 }
 }
 }
}

Cada servidor necesita:

• command: el programa que ejecuta el servidor (npx, node, python, etc.)
• args: argumentos del comando (nombre del paquete, flags)
• env: variables de entorno (API keys, tokens, URLs). Opcional

Después de modificar settings.json, reinicia Claude Code con /mcp o cerrando y abriendo la sesión.

Configuración local vs global. Usa .claude/settings.json (dentro del proyecto) para MCPs que solo necesitas en ese proyecto. Usa ~/.claude/settings.json (home) para MCPs que usas en todos los proyectos (como GitHub o filesystem). La configuración local tiene prioridad sobre la global si hay conflicto de nombres.

Servidores populares

Los MCP servers más usados en 2026:

• GitHub: crear PRs, issues, revisar código, buscar repos
• Supabase: queries SQL, migraciones, gestión de proyectos
• Filesystem: acceso controlado a directorios específicos
• PostgreSQL: queries directas a base de datos
• Docker: gestionar contenedores, compose, logs
• Slack: enviar mensajes, leer canales, buscar conversaciones
• Brave Search / Exa / Tavily: búsquedas web en tiempo real
• Gmail / Google Calendar: leer y enviar emails, gestionar eventos
• Obsidian: leer y escribir notas de tu vault
• n8n: gestionar workflows de automatización
• Más de 100+ servidores disponibles

Ejemplo: GitHub MCP

El MCP más útil para desarrollo. Permite a Claude Code interactuar con repositorios sin usar la terminal.

// .claude/settings.json
{
 "mcpServers": {
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"],
 "env": {
 "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tutoken"
 }
 }
 }
}

Cómo obtener el token: GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens. Permisos mínimos recomendados: Contents (read/write), Pull requests (read/write), Issues (read/write). Limita el token a los repos que necesites.

Con este servidor configurado, puedes pedirle a Claude Code:

• "Crea un PR con los cambios actuales"
• "Lista los issues abiertos del repo"
• "Revisa el PR #42 y deja comentarios"
• "Busca repos de Python sobre machine learning"

Claude Code usa las herramientas de GitHub automáticamente sin que tengas que especificar cuál usar.

Ejemplo: Filesystem MCP

// Acceso controlado a directorios específicos
{
 "mcpServers": {
 "filesystem": {
 "command": "npx",
 "args": [
 "-y",
 "@modelcontextprotocol/server-filesystem",
 "/Users/tu-usuario/documentos",
 "/Users/tu-usuario/proyectos"
 ]
 }
 }
}

El servidor filesystem permite a Claude Code acceder a directorios fuera del proyecto actual. Útil cuando necesitas referenciar documentación, configuraciones compartidas, o archivos de otros proyectos.

Importante: solo los directorios que listes en args serán accesibles. Esto es un control de seguridad deliberado. No pongas "/" o tu home completo: limita el acceso a los directorios que realmente necesitas.

Ejemplo: Supabase MCP

Conecta Claude Code directamente con tu proyecto Supabase para ejecutar queries, crear migraciones y gestionar la base de datos.

{
 "mcpServers": {
 "supabase": {
 "command": "npx",
 "args": ["-y", "supabase-mcp-server"],
 "env": {
 "SUPABASE_ACCESS_TOKEN": "sbp_tu_token",
 "SUPABASE_PROJECT_REF": "tu-project-ref"
 }
 }
 }
}

Cómo obtener las credenciales: el Access Token se genera en supabase.com → Account → Access Tokens. El Project Ref es el ID del proyecto visible en la URL del dashboard (las letras después de "project/").

Con Supabase MCP puedes:

• "Muéstrame las tablas de la base de datos"
• "Ejecuta un SELECT de los últimos 100 usuarios registrados"
• "Crea una migración para añadir la columna email_verified a users"
• "Lista las edge functions del proyecto"

Para más detalle, revisa nuestro tutorial completo de MCP + Supabase.

Ejemplo: Slack MCP

Permite a Claude Code leer canales, buscar mensajes y enviar notificaciones.

{
 "mcpServers": {
 "slack": {
 "command": "npx",
 "args": ["-y", "@anthropic/mcp-server-slack"],
 "env": {
 "SLACK_BOT_TOKEN": "xoxb-tu-bot-token"
 }
 }
 }
}

Cómo configurar el bot: Ve a api.slack.com/apps, crea una nueva app, activa los permisos (scopes) que necesites: channels:read, channels:history, chat:write para lo básico. Instala la app en tu workspace y copia el Bot User OAuth Token.

Casos de uso prácticos:

• "Lee los últimos mensajes del canal #dev y haz un resumen"
• "Envía un mensaje al canal #deploys diciendo que el release v2.3 está listo"
• "Busca en Slack quién mencionó el bug de login esta semana"

Ejemplo: Browser/Search MCP

Para dar a Claude Code acceso a búsquedas web y contenido actual, hay varias opciones.

Exa (búsqueda semántica):

{
 "mcpServers": {
 "exa": {
 "command": "npx",
 "args": ["-y", "exa-mcp-server"],
 "env": {
 "EXA_API_KEY": "tu-api-key"
 }
 }
 }
}

Tavily (búsqueda + extracción):

{
 "mcpServers": {
 "tavily": {
 "command": "npx",
 "args": ["-y", "tavily-mcp-server"],
 "env": {
 "TAVILY_API_KEY": "tu-api-key"
 }
 }
 }
}

Exa es mejor para búsquedas semánticas (encontrar contenido similar a un concepto). Tavily es mejor para búsquedas factuales + extracción de contenido de páginas web. Ambos tienen planes gratuitos suficientes para uso personal.

Con un MCP de búsqueda configurado, Claude Code puede:

• "Busca la documentación actual de Next.js 15 sobre Server Components"
• "Encuentra el precio actual de la API de OpenAI"
• "Investiga las mejores prácticas de seguridad para JWT en 2026"

Seguridad y buenas prácticas

Configurar MCPs implica dar acceso a Claude Code a servicios externos. Sigue estas reglas para minimizar riesgos:

1. Principio de mínimo privilegio. Crea tokens con los permisos mínimos necesarios. Si solo necesitas leer repos de GitHub, no des permisos de escritura. Si solo necesitas leer canales de Slack, no des permisos de envío.

2. Tokens por proyecto, no globales. Cuando sea posible, usa tokens diferentes para cada proyecto. Si un token se compromete, el impacto está contenido.

3. Nunca commits con tokens. Añade .claude/settings.json a tu .gitignore. Mejor aún: usa variables de entorno del sistema y referéncialas en settings.json. O usa un fichero .env que settings.json lea.

4. Revisa las acciones. Claude Code pide confirmación antes de ejecutar acciones que modifiquen datos. No aceptes automáticamente: lee qué va a hacer, especialmente con MCPs que pueden escribir datos (Supabase, GitHub, Slack).

5. Rota tokens periódicamente. Especialmente si trabajas en equipo o si el settings.json ha sido visible en algún momento. La mayoría de servicios permiten revocar y recrear tokens sin perder configuración.

Troubleshooting completo

Problemas comunes al configurar MCP y cómo resolverlos:

"Server failed to start". El comando no se ejecutó. Verifica que el programa existe ejecutando el comando manualmente en terminal. Para MCPs basados en npx, prueba: npx -y @paquete/nombre --help. Si falla, puede ser un problema de Node.js (versión antigua) o de permisos.

"No tools available". El servidor arrancó pero no expone herramientas. Causas comunes: versión incorrecta del paquete, faltan variables de entorno requeridas, o el servidor necesita autenticación que no se configuró. Revisa los logs con /mcp.

API key inválida. El token ha expirado, no tiene los permisos necesarios, o está mal copiado (espacios en blanco al principio/final). Solución: regenera el token y cópialo con cuidado.

Timeout al iniciar. Algunos servidores tardan en arrancar (especialmente los que descargan dependencias con npx la primera vez). Espera 30 segundos y ejecuta /mcp para verificar. La segunda ejecución será más rápida porque npx cachea los paquetes.

Conflicto de nombres. Si tienes dos servidores con el mismo nombre en configuración local y global, el local tiene prioridad. Usa nombres descriptivos y únicos.

El MCP funciona pero Claude Code no lo usa. Claude Code decide cuándo usar cada herramienta. Si crees que debería usarla, menciónala explícitamente: "Usa el MCP de GitHub para crear un PR" en vez de solo "Crea un PR".

Error "permission denied". El token no tiene permisos suficientes para la acción solicitada. Revisa los scopes del token en el servicio correspondiente. Para GitHub, necesitas write en Pull Requests para crear PRs. Para Slack, necesitas chat:write para enviar mensajes.

Usa /mcp dentro de Claude Code para ver el estado de todos los servidores configurados y diagnosticar problemas. Muestra qué servidores están activos, cuáles fallaron y cuántas herramientas expone cada uno.

Crear tu propio MCP server

Si necesitas conectar Claude Code con una herramienta que no tiene MCP oficial, puedes crear el tuyo. El protocolo es abierto y hay SDKs disponibles.

Con TypeScript:

// server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
 name: "mi-servidor",
 version: "1.0.0"
});

// Define una herramienta
server.tool(
 "buscar_productos",
 "Busca productos en el catálogo interno",
 { query: z.string(), limit: z.number().optional() },
 async ({ query, limit }) => {
   // Tu lógica de búsqueda aquí
   const results = await buscarEnCatalogo(query, limit || 10);
   return {
     content: [{ type: "text", text: JSON.stringify(results) }]
   };
 }
);

// Inicia el servidor
const transport = new StdioServerTransport();
await server.connect(transport);

Con Python:

# server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("mi-servidor")

@mcp.tool()
def buscar_productos(query: str, limit: int = 10) -> str:
    """Busca productos en el catálogo interno."""
    results = buscar_en_catalogo(query, limit)
    return json.dumps(results)

if __name__ == "__main__":
    mcp.run()

Después, configúralo en settings.json como cualquier otro MCP:

{
 "mcpServers": {
 "mi-catalogo": {
 "command": "node",
 "args": ["./mcp-servers/server.js"]
 }
 }
}

Los SDKs gestionan toda la comunicación del protocolo. Tú solo defines las herramientas (nombre, descripción, parámetros, lógica). El SDK se encarga de anunciarlas a Claude Code y de serializar/deserializar las llamadas.

Siguiente paso

Configura tu primer MCP server (GitHub es el más útil para empezar). Después explora MCP + Supabase para bases de datos y MCP + GitHub para automatización de repositorios. Si quieres entender la base de Claude Code primero, lee qué es Claude Code.

Preguntas frecuentes

Es seguro dar acceso a Claude Code a mis servicios via MCP?

MCP pide confirmación antes de ejecutar acciones destructivas. Para minimizar riesgos: usa tokens con permisos mínimos (solo lectura cuando sea suficiente), configura MCPs por proyecto (no global) para limitar el alcance, nunca pongas tokens directamente en código que vayas a commitear, y rota tokens periódicamente.

Cómo creo mi propio MCP server?

Necesitas un programa que implemente el protocolo MCP sobre stdio. El SDK oficial (@modelcontextprotocol/sdk en TypeScript, mcp en Python) simplifica el proceso a definir herramientas con nombre, descripción y parámetros. El SDK gestiona toda la comunicación. Un servidor básico se crea en menos de 50 líneas de código.

Puedo usar MCPs con otros clientes que no sean Claude Code?

Sí. MCP es un protocolo abierto. Otros clientes como Cursor, Windsurf y aplicaciones que implementen el protocolo MCP pueden usar los mismos servidores. La configuración varía por cliente, pero los servidores son reutilizables.

Cuántos MCPs puedo tener activos a la vez?

No hay un límite técnico estricto, pero cada MCP es un proceso que consume memoria. En la práctica, 10-15 MCPs funcionan bien. Si notas que Claude Code tarda en iniciar o consume mucha RAM, reduce el número de MCPs globales y usa configuración por proyecto para los que no necesitas siempre.