Modulo 05: MCP: conectividad total

MCP: el protocolo universal para conectar IA

Antes de MCP (Model Context Protocol), cada herramienta de IA tenia su propia forma de integrarse con servicios externos. Plugins propietarios, APIs ad-hoc, formatos incompatibles. MCP resuelve esto creando un estandar universal: un unico protocolo para que cualquier modelo de IA se conecte con cualquier servicio.

MCP define tres primitivas fundamentales:

• Tools (Herramientas): Acciones que el modelo puede ejecutar. Ejemplo: crear un issue en GitHub, enviar un email, ejecutar una query SQL.
• Resources (Recursos): Datos que el modelo puede leer. Ejemplo: contenido de un archivo, registros de una base de datos, documentacion.
• Prompts (Plantillas): Templates reutilizables que guian la interaccion. Ejemplo: "analiza este repositorio", "genera un informe de seguridad".

Arquitectura del protocolo:

+------------------+          +------------------+
|   MCP Client     |  JSON-RPC |   MCP Server     |
|  (Claude Code,   | <-------> |  (GitHub, DB,    |
|   Cursor, etc.)  |   stdio   |   API propia)    |
+------------------+          +------------------+
        |                              |
   Envia peticiones             Expone tools,
   de tools/resources           resources, prompts

Servers MCP listos para usar

El ecosistema MCP crece rapidamente. Estos son los servers mas utiles disponibles hoy:

• GitHub: Gestionar PRs, issues, buscar codigo, crear branches, revisar diffs. Ideal para flujos de desarrollo completos sin salir del editor.
• Supabase: Ejecutar SQL, gestionar migraciones, listar tablas, consultar datos. Acceso directo a tu base de datos PostgreSQL.
• Filesystem: Leer y escribir archivos fuera del directorio del proyecto. Util para acceder a configuraciones globales o documentacion externa.
• Docker: Gestionar contenedores, leer logs, ejecutar docker-compose. Control total de tu infraestructura local.
• Obsidian: Buscar notas, leer por tags, crear entradas. Tu segundo cerebro accesible desde la IA.
• n8n: Listar workflows, ejecutar flujos, consultar ejecuciones. Automatizacion visual controlada por IA.
• Notion: Leer paginas, consultar databases, crear entradas. Gestion de proyectos integrada.
• Stripe: Consultar pagos, gestionar clientes, verificar suscripciones. Finanzas accesibles desde tu editor.
• Slack: Enviar mensajes, leer canales, buscar conversaciones. Comunicacion del equipo integrada.

Ejemplo: configurar el server MCP de GitHub:

// .claude/settings.json o .mcp.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_tu_token_aqui"
      }
    }
  }
}

Crear tu propio server MCP con Python

Cuando ningun server existente cubre tu necesidad, puedes crear uno propio. Con la libreria FastMCP de Python, es sorprendentemente sencillo.

Instalacion:

pip install fastmcp

Ejemplo completo: un server MCP para tu CRM interno:

from fastmcp import FastMCP
import json

mcp = FastMCP("CRM Server")

# --- TOOLS (acciones) ---
@mcp.tool()
def buscar_cliente(nombre: str) -> str:
    """Busca un cliente por nombre en el CRM."""
    # En produccion: query a tu base de datos
    clientes = [
        {"id": 1, "nombre": "Acme Corp", "email": "contacto@acme.com", "plan": "pro"},
        {"id": 2, "nombre": "TechStart", "email": "info@techstart.es", "plan": "basic"},
    ]
    resultados = [c for c in clientes if nombre.lower() in c["nombre"].lower()]
    return json.dumps(resultados, ensure_ascii=False)

@mcp.tool()
def crear_lead(nombre: str, email: str, origen: str = "web") -> str:
    """Crea un nuevo lead en el CRM."""
    # En produccion: INSERT en base de datos
    lead = {"nombre": nombre, "email": email, "origen": origen, "estado": "nuevo"}
    return json.dumps({"ok": True, "lead": lead}, ensure_ascii=False)

# --- RESOURCES (datos) ---
@mcp.resource("crm://clientes/lista")
def lista_clientes() -> str:
    """Devuelve la lista completa de clientes activos."""
    return json.dumps([
        {"id": 1, "nombre": "Acme Corp", "plan": "pro", "mrr": 299},
        {"id": 2, "nombre": "TechStart", "plan": "basic", "mrr": 49},
        {"id": 3, "nombre": "DataFlow", "plan": "enterprise", "mrr": 999},
    ], ensure_ascii=False)

# --- PROMPTS (plantillas) ---
@mcp.prompt()
def analisis_cliente(nombre: str) -> str:
    """Genera un prompt para analizar un cliente."""
    return f"""Analiza el cliente {nombre} en nuestro CRM:
1. Busca su informacion con buscar_cliente
2. Revisa su plan actual y facturacion
3. Identifica oportunidades de upsell
4. Sugiere acciones concretas para el equipo comercial"""

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

Con menos de 50 lineas de Python tienes un server MCP funcional que conecta tu CRM con cualquier cliente MCP compatible: Claude Code, Cursor, Windsurf, o tu propia aplicacion.

Crear server MCP con TypeScript

Si prefieres TypeScript, el SDK oficial de MCP ofrece una experiencia igual de limpia.

Instalacion:

npm install @modelcontextprotocol/sdk

Ejemplo: server MCP para una API interna:

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: "api-interna",
  version: "1.0.0",
});

// Tool: consultar estado de servicios
server.tool(
  "estado_servicios",
  "Consulta el estado de los servicios internos",
  {},
  async () => {
    // En produccion: llamada a tu API de monitoring
    const servicios = [
      { nombre: "API Principal", estado: "ok", latencia: "45ms" },
      { nombre: "Base de datos", estado: "ok", latencia: "12ms" },
      { nombre: "Cola de mensajes", estado: "warning", latencia: "230ms" },
    ];
    return {
      content: [{ type: "text", text: JSON.stringify(servicios, null, 2) }],
    };
  }
);

// Tool: buscar en documentacion interna
server.tool(
  "buscar_docs",
  "Busca en la documentacion interna de la empresa",
  { query: z.string().describe("Termino de busqueda") },
  async ({ query }) => {
    // En produccion: busqueda en tu wiki/Confluence/Notion
    return {
      content: [{ type: "text", text: `Resultados para: ${query}` }],
    };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

Configurar MCP en Claude Code

La configuracion de servers MCP se hace en el archivo .mcp.json en la raiz del proyecto o en la configuracion global de Claude Code.

Ejemplo completo con multiples servers:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_KEY": "${SUPABASE_SERVICE_KEY}"
      }
    },
    "crm-local": {
      "command": "python",
      "args": ["./mcp-servers/crm_server.py"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ruta/a/docs"]
    }
  }
}

MCP en produccion

Pasar de un server MCP en desarrollo a produccion requiere considerar varios aspectos criticos.

Autenticacion y autorizacion:

• Tokens rotados periodicamente (no hardcoded)
• Scopes minimos necesarios (read-only cuando sea posible)
• API keys por entorno (dev/staging/prod separados)

Rate limiting:

from fastmcp import FastMCP
from functools import wraps
import time

# Rate limiter simple
call_log = {}

def rate_limit(max_calls: int = 10, window: int = 60):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            now = time.time()
            key = func.__name__
            calls = call_log.get(key, [])
            calls = [t for t in calls if now - t < window]
            if len(calls) >= max_calls:
                return f"Rate limit: max {max_calls} llamadas cada {window}s"
            calls.append(now)
            call_log[key] = calls
            return func(*args, **kwargs)
        return wrapper
    return decorator

Logging y auditoria:

• Registrar cada llamada a tools con timestamp, usuario y parametros
• Alertar sobre patrones anomalos (demasiadas llamadas, errores repetidos)
• Retener logs segun la politica de la empresa (RGPD: 90 dias operacionales)

Circuit breakers:

# Si un servicio externo falla 3 veces seguidas,
# dejar de llamarlo durante 60 segundos
circuit_state = {"failures": 0, "open_until": 0}

def call_with_circuit_breaker(func):
    if time.time() < circuit_state["open_until"]:
        return "Servicio temporalmente no disponible"
    try:
        result = func()
        circuit_state["failures"] = 0
        return result
    except Exception:
        circuit_state["failures"] += 1
        if circuit_state["failures"] >= 3:
            circuit_state["open_until"] = time.time() + 60
        raise

Monitorizacion:

• Metricas de latencia por tool (p50, p95, p99)
• Tasa de errores por server MCP
• Uso de tokens/creditos por herramienta
• Dashboard con estado en tiempo real de todos los servers

Un server MCP en produccion no es solo codigo que funciona. Es codigo que funciona de forma fiable, segura y observable. Aplica los mismos estandares que a cualquier microservicio critico.