Servidores MCP — conectar herramientas externas a Claude Code / Cursor

Model Context Protocol (MCP) es el estándar para exponer herramientas externas y datos a los agentes de IA. La especificación abierta de Anthropic, adoptada por Claude Code, Cursor, Continue y otros, comparten la misma interfaz.

En términos sencillos: "Quiero que GPT o Claude accedan directamente a mi sistema de archivos, BD o GitHub, sin escribir wrappers de API personalizados cada vez."

Creo que lo que hace especial a MCP no es la tecnología en sí, sino el cambio de paradigma: antes cada integración era un proyecto separado; ahora un solo servidor MCP sirve a cualquier agente compatible. Porque eso es exactamente lo que lo convierte en infraestructura y no solo en una librería más.

Esta guía cubre los conceptos principales, configuraciones comunes de servidores, depuración y seguridad.

TL;DR

1. MCP es JSON-RPC sobre stdio/SSE: expone herramientas mediante RPC estandarizado
2. Servidores oficiales: filesystem, GitHub, Slack, Postgres, Puppeteer, etc. (@modelcontextprotocol/server-*)
3. Una sola configuración de cliente: Claude Code usa ~/.claude/settings.json, Cursor usa su interfaz de Configuración; mismo esquema JSON
4. Regla de seguridad n.º 1: preferir servidores de solo lectura; para los de escritura, solo directorios en la lista de permitidos explícita

Requisitos previos

• Node.js 20+ (para npx)
• Un cliente compatible con MCP — Claude Code o Cursor
• Tokens de API para los servicios que vayas a exponer (GitHub PAT, Slack, etc.)

1. Conceptos de MCP en 30 segundos (glosario)

2. Añadir MCP en Claude Code

2.1 Archivo de configuración (settings.json)

~/.claude/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/me/projects",
        "/Users/me/notes"
      ]
    }
  }
}

• Los argumentos del comando son los directorios a exponer. Lista de permitidos: nada más es accesible.
• Rutas absolutas. ~/ no se expande.

2.2 Reiniciar Claude Code

# Después de terminar la sesión anterior
claude

2.3 Verificar

Dentro de Claude Code:

¿Qué herramientas están disponibles?

Si aparecen read_file, write_file y list_directory del MCP de filesystem, la configuración es correcta.

3. Añadir MCP en Cursor

Configuración (⌘,) → Características → MCP → Añadir servidor. JSON:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

Mismo esquema. Se puede compartir la configuración con Claude Code: copiar ~/.claude/settings.json.

4. Seis servidores habituales

4.1 Filesystem

"filesystem": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ruta/al/dir/permitido"]
}

Leer / escribir / buscar archivos. Impone una lista blanca de rutas.

4.2 GitHub

"github": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}

Issues, PRs, búsqueda de código. Ámbitos del PAT al mínimo necesario (repo, read:user).

4.3 Slack

"slack": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-slack"],
  "env": {
    "SLACK_BOT_TOKEN": "xoxb-...",
    "SLACK_TEAM_ID": "T..."
  }
}

Lecturas y envíos en canales. Preferir token de bot sobre token de usuario.

4.4 PostgreSQL (solo lectura)

"postgres": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-postgres",
    "postgresql://readonly_user:pass@localhost/mydb"
  ]
}

Conectar como usuario de solo lectura: la IA puede ejecutar consultas arbitrarias, así que dividir los privilegios.

4.5 Puppeteer

"puppeteer": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
}

Automatización real del navegador. Capturas de pantalla, manipulación del DOM, ejecución de JS.

4.6 SQLite

"sqlite": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sqlite", "/ruta/a/db.sqlite"]
}

Ideal para análisis local de SQLite.

5. Gestión de secretos con 1Password

No escribir tokens en texto plano en JSON. Usar el patrón descrito en multi-os/password-manager:

Opción A — plantilla de chezmoi

Colocar ~/.claude/settings.json bajo chezmoi y usar {{ onepasswordRead "op://..." }}.

Opción B — script wrapper

# ~/bin/mcp-github.sh
#!/bin/bash
export GITHUB_PERSONAL_ACCESS_TOKEN="$(op item get GitHub --fields token --reveal)"
exec npx -y @modelcontextprotocol/server-github

settings.json:

"github": {
  "command": "/Users/me/bin/mcp-github.sh"
}

El CLI de op se desbloquea automáticamente mediante biometría de GUI: fluido y sin fricción.

6. Escribir un servidor MCP propio

Diez minutos para exponer tu propia herramienta. Node.js (my-server.js):

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
const server = new Server(
  { name: "my-tools", version: "0.1.0" },
  { capabilities: { tools: {} } }
);
 
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "echo",
      description: "Hacer eco de la entrada",
      inputSchema: {
        type: "object",
        properties: { msg: { type: "string" } },
        required: ["msg"],
      },
    },
  ],
}));
 
server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name === "echo") {
    return { content: [{ type: "text", text: req.params.arguments.msg }] };
  }
  throw new Error(`Herramienta desconocida: ${req.params.name}`);
});
 
await server.connect(new StdioServerTransport());

"my-tools": {
  "command": "node",
  "args": ["/Users/me/code/my-server.js"]
}

Ver los ejemplos oficiales del SDK de MCP.

7. Depuración

Las herramientas no aparecen

• Reiniciar completamente el cliente (Claude Code/Cursor).
• Verificar que npx es ejecutable: which npx / Node 20+.
• Revisar los logs del servidor: en Claude Code, verificar los logs del sistema o stderr.

MCP Inspector

Herramienta de depuración oficial:

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

Interfaz web para llamadas RPC directas: permite visualizar definiciones de herramientas y respuestas.

Respuestas lentas

• Primera llamada: npx -y descarga el paquete (lento la primera vez, rápido tras la caché).
• Instalación permanente: npm i -g @modelcontextprotocol/server-filesystem y luego command: "mcp-server-filesystem".

8. Seguridad

Solo directorios en la lista de permitidos

Para filesystem, siempre pasar argumentos de ruta explícitos. Omitirlos expone todo el directorio home.

Usuarios de BD de solo lectura

Para Postgres/SQLite, crear un usuario de solo lectura separado. La IA no debe poder ejecutar DROP TABLE.

Ámbitos de token mínimos

GitHub PAT: repo + read:user. Sin admin:org.

Evitar fugas de entorno

No hacer commit de settings.json. Si es necesario, usar la integración con chezmoi o un gestor de secretos (§5).

No confiar en servidores MCP aleatorios

Ceñirse a los oficiales @modelcontextprotocol/* o proyectos de código abierto auditables. No dar tokens a paquetes npm de origen desconocido.

Verificación

1. Tras editar settings.json, reiniciar Claude Code → preguntar "mostrar herramientas disponibles" → aparecen las herramientas del nuevo servidor.
2. "Muéstrame los archivos en la raíz" (con el servidor filesystem).
3. "Resume los últimos 5 PRs" (servidor GitHub).
4. Verificar las definiciones de herramientas con MCP Inspector.
5. Intentar acceder a una ruta fuera de la lista de permitidos → debe ser rechazado.

Solución de problemas

npx -y no puede encontrar el paquete

• Los errores tipográficos en el nombre del paquete @modelcontextprotocol/server-XXX son habituales. Verificar la lista oficial.
• En registros npm corporativos, establecer el registro público como fallback en .npmrc.

La ruta falla en Windows

Escapar \ o usar / en JSON:

"args": ["-y", "@modelcontextprotocol/server-filesystem", "C:/Users/me/projects"]

Claude Code no reconoce el servidor

• Validar la sintaxis de ~/.claude/settings.json: jq . ~/.claude/settings.json.
• Evitar confusión con otras ubicaciones de settings.json (~/.claude.json, .claude/settings.json en el proyecto).

Faltan algunas herramientas en la respuesta

Los servidores con listado no determinista pueden variar al reiniciar. Hacer que el handler de listTools sea determinista.

Token comprometido accidentalmente

Rotarlo de inmediato (GitHub → Tokens de acceso personal → Revocar + reemitir). Limpiar el historial de git con git filter-repo.

Referencias

• Configuración de Claude Code — configuración del host
• Configuración de Cursor — configuración del host
• Flujo de trabajo multi-agente — división principal/secundario
• Gestor de contraseñas — seguridad de tokens
• Model Context Protocol (oficial)
• Pool oficial de servidores

Registro de cambios

• 2026-05-12: Primer borrador. Conceptos + configuración de cliente + 6 servidores + gestión de secretos + servidor personalizado + depuración + seguridad + cinco casos de solución de problemas.