Capítulo 5: Model Context Protocol (MCP)

¿Qué es MCP?

Model Context Protocol (MCP) es un estándar que permite conectar agentes a sistemas externos de forma estandarizada.

flowchart TB
    subgraph SDK["AGENT SDK"]
        Agent["Claude Agent"]
        Agent --> MCPLayer["MCP Layer"]
        MCPLayer --> Playwright["Playwright<br/>Browser"]
        MCPLayer --> GitHub["GitHub<br/>API"]
        MCPLayer --> Slack["Slack<br/>API"]
    end

Servidores MCP Populares

Servidor	Descripción
Playwright	Automatización de navegador
GitHub	Repositorios, issues, PRs
Slack	Mensajería
PostgreSQL	Base de datos
Filesystem	Acceso a archivos
Google Drive	Documentos en la nube

Ver más en: github.com/modelcontextprotocol/servers

Conectar un Servidor MCP

Servidor Externo (Subproceso)

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    mcp_servers={
        "playwright": {
            "command": "npx",
            "args": ["@playwright/mcp@latest"]
        }
    }
)

async for msg in query(
    prompt="Abre google.com y describe lo que ves",
    options=options
):
    print(msg)

TypeScript

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Abre google.com y describe lo que ves",
  options: {
    mcpServers: {
      playwright: {
        command: "npx",
        args: ["@playwright/mcp@latest"]
      }
    }
  }
})) {
  console.log(message);
}

Crear Herramientas Custom con MCP

Servidor MCP In-Process

Elimina la sobrecarga de subprocesos:

from claude_agent_sdk import (
    tool,
    create_sdk_mcp_server,
    ClaudeAgentOptions,
    ClaudeSDKClient
)

# Define herramientas con el decorador @tool
@tool("saludar", "Saluda a un usuario", {"nombre": str})
async def saludar(args):
    return {
        "content": [
            {"type": "text", "text": f"¡Hola, {args['nombre']}!"}
        ]
    }

@tool("sumar", "Suma dos números", {"a": int, "b": int})
async def sumar(args):
    resultado = args['a'] + args['b']
    return {
        "content": [
            {"type": "text", "text": f"La suma es: {resultado}"}
        ]
    }

# Crea el servidor
server = create_sdk_mcp_server(
    name="mis-herramientas",
    version="1.0.0",
    tools=[saludar, sumar]
)

# Usa el servidor
options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__saludar", "mcp__tools__sumar"]
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Saluda a María y suma 5 + 3")
    async for msg in client.receive_response():
        print(msg)

Ejemplo: Agente con Base de Datos

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions
import sqlite3

conn = sqlite3.connect(":memory:")
conn.execute("CREATE TABLE usuarios (id INT, nombre TEXT, email TEXT)")
conn.execute("INSERT INTO usuarios VALUES (1, 'Ana', '[email protected]')")
conn.commit()

@tool("consultar_db", "Ejecuta una consulta SQL", {"query": str})
async def consultar_db(args):
    cursor = conn.execute(args['query'])
    resultados = cursor.fetchall()
    return {
        "content": [
            {"type": "text", "text": str(resultados)}
        ]
    }

server = create_sdk_mcp_server(
    name="database",
    version="1.0.0",
    tools=[consultar_db]
)

options = ClaudeAgentOptions(
    mcp_servers={"db": server},
    allowed_tools=["mcp__db__consultar_db"]
)

async for msg in query(
    prompt="Muestra todos los usuarios de la base de datos",
    options=options
):
    print(msg)

Ejemplo: Agente con API Externa

import httpx
from claude_agent_sdk import tool, create_sdk_mcp_server

@tool("obtener_clima", "Obtiene el clima de una ciudad", {"ciudad": str})
async def obtener_clima(args):
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"https://wttr.in/{args['ciudad']}?format=j1"
        )
        data = response.json()
        temp = data['current_condition'][0]['temp_C']
        desc = data['current_condition'][0]['weatherDesc'][0]['value']

    return {
        "content": [
            {"type": "text", "text": f"{args['ciudad']}: {temp}°C, {desc}"}
        ]
    }

server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[obtener_clima]
)

Mezclar Servidores Internos y Externos

options = ClaudeAgentOptions(
    mcp_servers={
        # Servidor in-process (más rápido)
        "mis_tools": mi_servidor_interno,

        # Servidor externo (subproceso)
        "playwright": {
            "type": "stdio",
            "command": "npx",
            "args": ["@playwright/mcp@latest"]
        },

        # Otro servidor externo
        "github": {
            "type": "stdio",
            "command": "npx",
            "args": ["@modelcontextprotocol/server-github"]
        }
    }
)

Ventajas de MCP In-Process

Característica	In-Process	Externo
Latencia	Baja	Media
Debugging	Fácil	Complejo
Deploy	Simple	Más config
Aislamiento	Menor	Mayor

Ejemplo: Agente de Automatización Web

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    mcp_servers={
        "playwright": {
            "command": "npx",
            "args": ["@playwright/mcp@latest"]
        }
    },
    system_prompt="""Eres un agente de automatización web.
    Puedes navegar páginas, hacer clic en elementos,
    llenar formularios y extraer información."""
)

async for msg in query(
    prompt="Ve a Hacker News y dame los 3 títulos más votados",
    options=options
):
    print(msg)

Resumen

• MCP conecta agentes a sistemas externos
• Puedes usar servidores externos (subprocesos) o in-process
• @tool permite crear herramientas personalizadas
• Combina múltiples servidores según necesites