MCP en Claude Code: cómo conectar bases de datos y APIs

Tabla de Contenidos

• Referencia rápida
• Cómo funciona MCP
• Paso 1: agregar un servidor local (stdio)
• Paso 2: conectar un servidor remoto (HTTP)
• Paso 3: elegir el scope
• Paso 4: compartir la configuración sin subir secretos
• Paso 5: verificar que funciona
• 8 reglas de seguridad antes de conectar algo serio
• Y Superpowers, ¿dónde entra?
• Plan para tu equipo

Recién instalado, Claude Code lee archivos y ejecuta comandos en tu terminal. Para que consulte tu base de datos, revise tus issues o llame a una API, necesitas MCP (Model Context Protocol), el protocolo abierto que Anthropic publicó para conectar modelos con herramientas externas.

Esta guía explica cómo agregar servidores MCP, cómo compartirlos con tu equipo sin subir credenciales a Git y qué reglas de seguridad seguir antes de conectar algo serio.

Referencia rápida

Servidor	Transporte	Comando	Scope sugerido	Cuidado clave
Git local	stdio (uvx)	claude mcp add git -- uvx mcp-server-git	user	Revisa qué operaciones de escritura expone
PostgreSQL	stdio (npx)	claude mcp add db -- npx -y @bytebase/dbhub --dsn "$DATABASE_READONLY_URL"	project	Solo con un usuario de solo lectura
API remota	http	claude mcp add --transport http mi-api https://mcp.ejemplo.com/mcp	project	El token va en una variable, nunca en el archivo
Sistema de archivos	stdio (npx)	claude mcp add archivos -- npx -y @modelcontextprotocol/server-filesystem .	local	Limita la ruta al proyecto, nunca a la raíz del disco

Cómo funciona MCP

Claude Code actúa como cliente. Cada servidor MCP es un proceso o servicio que expone herramientas, por ejemplo run_query o list_issues. Durante la sesión, Claude ve esas herramientas, decide cuándo llamarlas y te pide permiso según tu configuración.

Hay dos formas de conectarse:

• stdio: Claude Code inicia el servidor como un proceso local (normalmente con npx o uvx) y se comunica por la entrada y salida estándar. Es lo habitual para herramientas que corren en tu máquina.
• http: el servidor vive en una URL remota. Es lo habitual para servicios en la nube. Muchos de los servicios grandes publican servidores MCP oficiales con autenticación OAuth.

Paso 1: agregar un servidor local (stdio)

La forma general es:

claude mcp add <nombre> -- <comando> [argumentos...]

El separador -- es obligatorio: separa las opciones de claude del comando que arranca el servidor. Sin él, Claude Code intenta interpretar los argumentos del servidor como suyos.

Ejemplo con un servidor de Git:

claude mcp add git -- uvx mcp-server-git

Ejemplo con PostgreSQL usando DBHub, apuntando a una variable de entorno con un usuario de solo lectura:

export DATABASE_READONLY_URL="postgresql://lectura:****@db.tuempresa.com:5432/analytics"
claude mcp add db -- npx -y @bytebase/dbhub --dsn "$DATABASE_READONLY_URL"

Paso 2: conectar un servidor remoto (HTTP)

claude mcp add --transport http mi-api https://mcp.ejemplo.com/mcp \
  --header "Authorization: Bearer $MI_API_TOKEN"

Si el servidor usa OAuth, no pongas el header: entra a la sesión, ejecuta /mcp y sigue el flujo de autenticación en el navegador.

Paso 3: elegir el scope

Cada servidor se guarda en uno de tres ámbitos, que eliges con --scope:

• local (por defecto): solo para ti y solo en este proyecto. Útil para pruebas o servidores con credenciales personales.
• project: se escribe en .mcp.json, en la raíz del repo. Todo el equipo lo recibe al clonar. Claude Code pide aprobación la primera vez que alguien usa un servidor de proyecto.
• user: para ti en todos tus proyectos. Ideal para herramientas generales como Git.

claude mcp add --scope project db -- npx -y @bytebase/dbhub --dsn '${DATABASE_READONLY_URL}'

Paso 4: compartir la configuración sin subir secretos

El archivo .mcp.json acepta variables de entorno con la sintaxis ${VARIABLE} (y ${VARIABLE:-valor_por_defecto}). Así el archivo puede ir al repo sin credenciales:

{
  "mcpServers": {
    "mi-api": {
      "type": "http",
      "url": "https://mcp.ejemplo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MI_API_TOKEN}"
      }
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_READONLY_URL}"]
    }
  }
}

Cada desarrollador exporta sus propias variables (export MI_API_TOKEN=...) o las carga desde un gestor de secretos, y nadie tiene que tocar el archivo.

Paso 5: verificar que funciona

claude mcp list        # estado de todos los servidores
claude mcp get db      # detalle de uno
claude mcp remove db   # eliminarlo

Dentro de una sesión, /mcp muestra qué servidores están conectados y qué herramientas exponen. Si un servidor aparece con error, la causa más común es una variable de entorno que no está definida en la shell donde abriste Claude Code.

8 reglas de seguridad antes de conectar algo serio

1. Mínimo privilegio. Usuarios de base de datos de solo lectura, tokens con los permisos justos. Nunca le des al agente un usuario administrador.
2. Cero secretos en el repo. Variables de entorno en .mcp.json, siempre.
3. Rutas acotadas. El servidor de archivos solo debe ver la carpeta del proyecto.
4. Servidores oficiales o revisados. Prefiere los que publica el propio proveedor del servicio. Un servidor MCP ejecuta código en tu máquina: revisa de dónde viene antes de instalarlo.
5. Aprobación humana para lo que escribe. Usa los permisos de Claude Code para que las herramientas que modifican datos pidan confirmación, o un hook PreToolUse con un matcher como mcp__db__.* para bloquear o registrar ciertas llamadas.
6. Timeouts razonables. Si un servidor tarda en arrancar (la primera descarga con npx suele ser lenta), sube el tiempo de espera con la variable MCP_TIMEOUT, en milisegundos.
7. Límite de salida. Si una herramienta devuelve resultados enormes, ajusta MAX_MCP_OUTPUT_TOKENS y pide consultas con LIMIT para no llenar el contexto del modelo.
8. Réplicas antes que producción. Para análisis, conecta una réplica o un entorno de staging, no la base principal.

Y Superpowers, ¿dónde entra?

MCP le da a Claude Code acceso a herramientas. Superpowers le da un método: un plugin de skills que lo obliga a diseñar antes de programar, escribir un plan por pasos y trabajar con pruebas primero. Son complementarios: con MCP, Claude puede consultar tu base de datos; con Superpowers, lo hace dentro de un plan revisado.

Si todavía no lo tienes, la guía de cómo instalar Superpowers en Claude Code explica la instalación desde el marketplace en cinco minutos.

Plan para tu equipo

1. Estandariza la herramienta. Instala Claude Code en el equipo y decide qué servidores son de uso general (scope user) y cuáles del proyecto.
2. Crea credenciales para la IA. Pide a infraestructura un usuario de base de datos dedicado, de solo lectura y con acceso limitado a los esquemas necesarios.
3. Versiona .mcp.json. Súbelo al repo con variables de entorno y documenta en el README qué variables necesita cada desarrollador.
4. Mide el impacto. Si el equipo resuelve más rápido, eso cambia tu estructura de costos. Haz la cuenta con la calculadora de margen de ganancia.