​
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