Guía de MCP Server en Claude Code: integra SaaS sin romper la seguridad

Un MCP Server convierte Claude Code en una herramienta capaz de leer issues de GitHub, buscar documentación de equipo, consultar Notion, Google Drive, CRM o APIs internas. Esa potencia también cambia el riesgo. Un scope demasiado amplio, un token guardado en .mcp.json, una autorización OAuth mal revisada, un npx que no arranca en Windows o una respuesta enorme que dispara el aviso de 10,000 tokens pueden arruinar una integración que parecía sencilla.

Esta guía está escrita para usar MCP en trabajo real. La idea no es instalar muchos conectores, sino empezar pequeño, revisar permisos, confirmar el estado con /mcp y dejar una configuración que el equipo pueda entender.

Qué cambia MCP en Claude Code

MCP significa Model Context Protocol. Es un estándar para conectar clientes de IA con herramientas y fuentes de datos externas. Claude Code actúa como cliente MCP y llama a las herramientas que expone cada servidor.

Sin MCP, Claude Code ve principalmente el repositorio y el contexto que le das. Con MCP, puede ver documentos, métricas, tickets, datos de clientes o servicios internos. Por eso la primera pregunta no es “qué servidor instalo”, sino “qué datos puede ver este proyecto, con qué permisos y con qué revisión humana”.

Para la parte de permisos conviene leer también la guía de permisos de Claude Code y las buenas prácticas de seguridad.

Transporte	Uso recomendado	Riesgo principal
`stdio`	Servidores locales con `npx`, Python o binarios internos	En Windows suele hacer falta `cmd /c npx`
`http`	MCP remoto, SaaS y OAuth	Revisar workspace y scopes de OAuth
`sse`	Compatibilidad con servidores antiguos	Para nuevas integraciones suele ser mejor HTTP

Elige el scope antes de conectar

claude mcp add permite --scope local, --scope project y --scope user. Este detalle define dónde queda disponible el servidor.

scope	Significado	Cuándo usarlo
`local`	Solo el proyecto actual en tu máquina	Pruebas, clientes, conexiones con secretos
`project`	Se guarda en `.mcp.json` y se comparte con el repo	Definiciones comunes para el equipo
`user`	Disponible en todos tus proyectos de Claude Code	Herramientas personales realmente genéricas

Empieza con local. Sube a project cuando el equipo necesite compartir nombres y comandos. Usa user con cuidado, sobre todo si trabajas con varios clientes.

claude mcp add --scope local --transport stdio repo-files -- npx -y @modelcontextprotocol/server-filesystem ./docs

claude mcp add --scope project --transport http team-docs https://mcp.example.com/mcp

claude mcp add --scope user --transport http personal-notes https://mcp.example.com/mcp

Los servidores project-scoped requieren aprobación de proyecto. No lo veas como una molestia: es el punto donde decides si ese repositorio confía en ese servidor.

Windows: usa cmd /c npx

En Windows puede ocurrir que npx funcione en PowerShell, pero falle cuando Claude Code intenta lanzar el servidor MCP por stdio. La forma práctica es envolverlo con cmd /c.

claude mcp add --scope local --transport stdio repo-files -- cmd /c npx -y @modelcontextprotocol/server-filesystem "C:\Users\masa\work\claudecode-lab\docs"

En .mcp.json, separa command y args.

{
  "mcpServers": {
    "repo-files": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\masa\\work\\claudecode-lab\\docs"
      ],
      "env": {}
    }
  }
}

No empieces dando acceso a todo tu directorio de usuario. Limita la carpeta a docs, reports o un repositorio de prueba. Si el servidor puede escribir, combínalo con la guía de hooks de Claude Code para bloquear acciones peligrosas.

MCP remoto, OAuth y verificación con /mcp

Para SaaS como Notion, Google Drive, GitHub o CRM, HTTP suele ser el transporte más claro.

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

Después ejecuta /mcp dentro de Claude Code. Ahí verificas conexión, autenticación y herramientas expuestas. Si el servidor usa OAuth, inicia el flujo desde /mcp, autoriza en el navegador y vuelve a revisar el estado.

/mcp

# Revisa:
# - si el servidor está connected
# - si OAuth está authenticated
# - qué workspace autorizaste
# - qué tools quedaron disponibles
# - si hay permisos write/admin cuando solo esperabas lectura

Para APIs internas con bearer token, puedes usar headers, pero evita guardar el token en archivos compartidos.

claude mcp add --scope local --transport http crm-readonly https://mcp.example.com/readonly \
  --header "Authorization: Bearer $CRM_READONLY_TOKEN"

Un .mcp.json de equipo debe guardar la estructura, no los secretos.

{
  "mcpServers": {
    "customer-docs": {
      "type": "http",
      "url": "https://mcp.example.com/customer-docs"
    },
    "github-readonly": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@example/github-readonly-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_READONLY_TOKEN}"
      }
    }
  }
}

Caso 1: GitHub y Notion para triage de issues

El primer valor aparece cuando reduces saltos entre issue, PR y especificación. Claude Code puede leer el issue con GitHub MCP, buscar requisitos en Notion o documentación interna, y resumir riesgos antes de editar código.

Lee el issue #248 en GitHub y busca requisitos relacionados en la documentación del producto.
No modifiques código todavía.
Devuelve:
1. Archivos probablemente afectados
2. Requisito claro
3. Preguntas abiertas
4. Plan mínimo y seguro de implementación

La frase “no modifiques código todavía” es importante. MCP da más contexto, pero también puede hacer que Claude avance demasiado rápido.

Caso 2: Google Drive para borradores de propuesta

En consultoría, formación y desarrollo a medida, la información suele estar en Drive: actas, propuestas antiguas, precios, notas de alcance. Un MCP de solo lectura puede ayudar a preparar un borrador sin exponer toda la empresa.

Busca en la carpeta "2026-05 Customer A".
Prepara un esquema de propuesta con:
1. Cinco problemas del cliente
2. Alcance probable
3. Dudas que debemos confirmar
4. Tres planes: formación, soporte de implementación y soporte operativo

Oculta nombres personales, correos y valores exactos de contrato.

La arquitectura segura es carpeta limitada, lectura solamente y revisión humana antes de enviar.

Caso 3: métricas de solo lectura

MCP también puede conectar dashboards, bases de datos o APIs internas. No entregues permisos de escritura en producción para un flujo analítico. Un endpoint de solo lectura es suficiente.

claude mcp add --scope local --transport http product-metrics https://mcp.example.com/readonly-metrics \
  --header "Authorization: Bearer $METRICS_READONLY_TOKEN"

Revisa fuentes de tráfico, PV por artículo y clics de conversión de los últimos 14 días.
Agrupa páginas por tema.
Recomienda cinco próximos artículos con la métrica que justifica cada uno.
Incluye dónde los datos son débiles o ruidosos.

Este flujo conecta directamente con monetización porque convierte el contenido en un ciclo de feedback.

Aviso de 10,000 tokens

Cuando una herramienta MCP devuelve demasiado contenido, Claude Code puede mostrar un aviso de 10,000 tokens. Suele pasar con búsquedas que devuelven cuerpos completos, listas largas de issues, HTML completo o consultas sin límite.

Primero reduce la salida.

Devuelve máximo 10 resultados.
Por resultado incluye solo título, URL, fecha de actualización y motivo de coincidencia.
No incluyas cuerpos completos hasta que pida uno específico.

Para análisis puntuales puedes elevar MAX_MCP_OUTPUT_TOKENS.

MAX_MCP_OUTPUT_TOKENS=50000 claude

$env:MAX_MCP_OUTPUT_TOKENS = "50000"
claude

Si necesitas esto todos los días, rediseña el servidor con paginación, filtros y resúmenes.

Errores frecuentes

El primer error es guardar secretos en .mcp.json. Un archivo project-scoped se comparte; usa variables de entorno, OAuth o gestor de secretos.

El segundo es usar --scope user por comodidad. Puede mezclar integraciones de clientes distintos.

El tercero es tratar documentos remotos como instrucciones. El texto externo puede contener prompt injection; trátalo como datos.

El cuarto es no revisar /mcp después de OAuth. Login correcto no significa workspace correcto.

El quinto es diseñar workflows que dependen de respuestas enormes. Lo estable es filtrar, resumir y pedir detalle bajo demanda.

Comandos de diagnóstico

claude mcp list
claude mcp get repo-files

Dentro de Claude Code:

/mcp

Para rehacer aprobación de project server:

claude mcp reset-project-choices

Prueba mínima:

Verifica solo la conexión repo-files.
Lista máximo 10 nombres de archivo bajo la carpeta permitida.
No leas contenido y no modifiques nada.

Monetización: vende el flujo seguro

MCP está cerca del dinero porque conecta Claude Code con sistemas reales. Pero “instalo MCP Server” no es una oferta fuerte. Mejor: “conecto GitHub, Notion, Google Drive y SaaS interno de forma segura para que el equipo use Claude Code cada semana”.

Producto barato: plantillas .mcp.json y checklist de seguridad
Servicio de equipo: revisión de GitHub, Notion, Drive y permisos
Implementación premium: scope, OAuth, hooks, monitoreo y formación

Empieza con el ejemplo de filesystem en una carpeta de prueba. Para equipos, usa un SaaS de solo lectura y un .mcp.json project-scoped. Después intégralo con Claude Code Harness Engineering.

Este artículo sigue la documentación oficial de Claude Code sobre claude mcp add, scopes, .mcp.json, /mcp, OAuth, project server approval y MAX_MCP_OUTPUT_TOKENS. La regla práctica es: scope pequeño, lectura primero, secretos fuera de archivos compartidos y verificación antes de usar.