Guías

MCP en el SDK

Extiende Claude Code con herramientas personalizadas usando servidores del Protocolo de Contexto de Modelo

Descripción general

Los servidores del Protocolo de Contexto de Modelo (MCP) extienden Claude Code con herramientas y capacidades personalizadas. Los MCP pueden ejecutarse como procesos externos, conectarse vía HTTP/SSE, o ejecutarse directamente dentro de tu aplicación SDK.

Configuración

Configuración básica

Configura servidores MCP en .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem"],
      "env": {
        "ALLOWED_PATHS": "/Users/me/projects"
      }
    }
  }
}

Usando servidores MCP en el SDK

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

for await (const message of query({
  prompt: "Lista archivos en mi proyecto",
  options: {
    mcpServers: {
      "filesystem": {
        command: "npx",
        args: ["@modelcontextprotocol/server-filesystem"],
        env: {
          ALLOWED_PATHS: "/Users/me/projects"
        }
      }
    },
    allowedTools: ["mcp__filesystem__list_files"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Tipos de transporte

Servidores stdio

Procesos externos que se comunican vía stdin/stdout:

// configuración .mcp.json
{
  "mcpServers": {
    "my-tool": {
      "command": "node",
      "args": ["./my-mcp-server.js"],
      "env": {
        "DEBUG": "${DEBUG:-false}"
      }
    }
  }
}

Servidores HTTP/SSE

Servidores remotos con comunicación de red:

// configuración de servidor SSE
{
  "mcpServers": {
    "remote-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

// configuración de servidor HTTP
{
  "mcpServers": {
    "http-service": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-Key": "${API_KEY}"
      }
    }
  }
}

Servidores MCP del SDK

Servidores en proceso que se ejecutan dentro de tu aplicación. Para información detallada sobre crear herramientas personalizadas, consulta la guía de Herramientas personalizadas:

Gestión de recursos

Los servidores MCP pueden exponer recursos que Claude puede listar y leer:

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

// Listar recursos disponibles
for await (const message of query({
  prompt: "¿Qué recursos están disponibles desde el servidor de base de datos?",
  options: {
    mcpServers: {
      "database": {
        command: "npx",
        args: ["@modelcontextprotocol/server-database"]
      }
    },
    allowedTools: ["mcp__list_resources", "mcp__read_resource"]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

Autenticación

Variables de entorno

// .mcp.json con variables de entorno
{
  "mcpServers": {
    "secure-api": {
      "type": "sse",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-API-Key": "${API_KEY:-default-key}"
      }
    }
  }
}

// Establecer variables de entorno
process.env.API_TOKEN = "your-token";
process.env.API_KEY = "your-key";

Autenticación OAuth2

La autenticación OAuth2 MCP en el cliente no está actualmente soportada.

Manejo de errores

Maneja las fallas de conexión MCP de manera elegante:

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

for await (const message of query({
  prompt: "Procesar datos",
  options: {
    mcpServers: {
      "data-processor": dataServer
    }
  }
})) {
  if (message.type === "system" && message.subtype === "init") {
    // Verificar estado del servidor MCP
    const failedServers = message.mcp_servers.filter(
      s => s.status !== "connected"
    );
    
    if (failedServers.length > 0) {
      console.warn("Falló la conexión:", failedServers);
    }
  }
  
  if (message.type === "result" && message.subtype === "error_during_execution") {
    console.error("Falló la ejecución");
  }
}

Recursos relacionados

Guía de herramientas personalizadas - Guía detallada sobre crear servidores MCP del SDK
Referencia del SDK de TypeScript
Referencia del SDK de Python
Permisos del SDK
Flujos de trabajo comunes