MCP Servers Guide

Los Model Context Protocol (MCP) Servers son puentes que permiten a Claude Code interactuar con APIs externas, bases de datos y herramientas en tiempo real.

¿Por qué usar MCP Servers?

  • Evitar alucinaciones: Context7 provee docs actualizados de librerías
  • Automatización: GitHub MCP gestiona repos, PRs, issues
  • Productividad: Playwright automatiza testing E2E

Servers Recomendados

Tier 1: Esenciales (instalar siempre)

Server Caso de uso Por qué es esencial
Context7 Docs actualizados Evita alucinaciones, docs por versión
GitHub Repos, PRs, issues Todo proyecto usa git

Context7

Resuelve el problema de docs desactualizados. Cuando preguntás sobre React 19 o Next.js 15, Context7 inyecta documentación actual en el contexto.

claude mcp add context7 npx -y @upstash/context7-mcp

Cómo funciona:

Tu: "¿Cómo usar useActionState en React 19?"
    ↓
Claude llama a Context7
    ↓
Context7 busca docs de React 19.x
    ↓
Respuesta con API real, no alucinada

GitHub

Gestiona repositorios, pull requests e issues sin salir de Claude.

claude mcp add github npx -y @modelcontextprotocol/server-github

Requiere variable de entorno:

export GITHUB_TOKEN="tu-token-aqui"

Tier 2: Productividad (según necesidad)

Server Caso de uso Cuándo usar
Playwright Testing E2E Proyectos web con tests
DuckDuckGo Búsquedas web Research durante desarrollo
Memory Bank Persistencia Proyectos largos

Playwright 

claude mcp add playwright npx @playwright/mcp@latest

Sequential Thinking

Workspace estructurado para problemas complejos.

claude mcp add sequential-thinking npx -y @modelcontextprotocol/server-sequential-thinking

Útil para: Arquitectura compleja, debugging, decisiones con trade-offs

Tier 3: Específicos por Stack

Server Stack Propósito
PostgreSQL Apps con Postgres Queries en lenguaje natural
Supabase Stack Supabase DB + Auth + Storage
Figma Design → Code Traducir diseños a código
Notion Knowledge base Acceso a documentación

Supabase 

claude mcp add supabase npx -y @supabase/mcp-server-supabase

Requiere variables de entorno:

export SUPABASE_URL="tu-url"
export SUPABASE_KEY="tu-key"

Configuración por Proyecto

Estrategia recomendada

Define MCPs globalmente y agregá específicos por proyecto:

Global (~/.claude.json):

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Proyecto con Supabase (~/Projects/mi-app/.mcp.json):

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_KEY": "${SUPABASE_KEY}"
      }
    }
  }
}

Deshabilitar MCPs por defecto 

// ~/.claude/settings.json
{
  "disabledMcpjsonServers": ["supabase", "playwright"]
}

Y re-habilitar en proyectos específicos:

// ~/Projects/app/.claude/settings.json
{
  "disabledMcpjsonServers": []
}

Tokens y Overhead 

MCP instalado pero NO usado  → 0 tokens extra
MCP usado (tool call)        → tokens del output
Tool descriptions            → ~100-500 tokens por server

Recomendación: 3-5 MCPs esenciales siempre activos. El resto activar según proyecto.

Troubleshooting

MCP no carga

  1. Verificar npm/npx instalado: which npx
  2. Primera ejecución es lenta (descarga paquetes)
  3. Reiniciar Claude Code después de agregar MCP

Variables de entorno no funcionan

Usar ${VAR_NAME} en configuración, no $VAR_NAME:

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

MCP no aparece en la lista 

# Verificar configuración
claude mcp list

# Ver logs de debug
claude --debug

Recursos