La función de conector del Protocolo de Contexto de Modelo (MCP) de Claude te permite conectarte a servidores MCP remotos directamente desde la API de Mensajes sin necesitar un cliente MCP separado.

Esta función requiere el encabezado beta: "anthropic-beta": "mcp-client-2025-04-04"

Características principales

  • Integración directa con la API: Conéctate a servidores MCP sin implementar un cliente MCP
  • Soporte para llamadas a herramientas: Accede a herramientas MCP a través de la API de Mensajes
  • Autenticación OAuth: Soporte para tokens Bearer de OAuth para servidores autenticados
  • Múltiples servidores: Conéctate a múltiples servidores MCP en una sola solicitud

Limitaciones

  • Del conjunto de características de la especificación MCP, actualmente solo se admiten las llamadas a herramientas.
  • El servidor debe estar expuesto públicamente a través de HTTP. Los servidores STDIO locales no pueden conectarse directamente.
  • El conector MCP actualmente no es compatible con Amazon Bedrock y Google Vertex.

Uso del conector MCP en la API de Mensajes

Para conectarte a un servidor MCP remoto, incluye el parámetro mcp_servers en tu solicitud a la API de Mensajes:

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-04-04" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "¿Qué herramientas tienes disponibles?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ]
  }'

Configuración del servidor MCP

Cada servidor MCP en el array mcp_servers admite la siguiente configuración:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "tool_configuration": {
    "enabled": true,
    "allowed_tools": ["example_tool_1", "example_tool_2"]
  },
  "authorization_token": "YOUR_TOKEN"
}

Descripción de campos

PropiedadTipoObligatorioDescripción
typestringActualmente solo se admite “url”
urlstringLa URL del servidor MCP. Debe comenzar con https://
namestringUn identificador único para este servidor MCP. Se utilizará en bloques mcp_tool_call para identificar el servidor y para diferenciar herramientas para el modelo.
tool_configurationobjectNoConfigurar el uso de herramientas
tool_configuration.enabledbooleanNoSi se deben habilitar las herramientas de este servidor (predeterminado: true)
tool_configuration.allowed_toolsarrayNoLista para restringir las herramientas permitidas (por defecto, todas las herramientas están permitidas)
authorization_tokenstringNoToken de autorización OAuth si es requerido por el servidor MCP. Ver especificación MCP.

Tipos de contenido de respuesta

Cuando Claude utiliza herramientas MCP, la respuesta incluirá dos nuevos tipos de bloques de contenido:

Bloque de uso de herramienta MCP

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

Bloque de resultado de herramienta MCP

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

Múltiples servidores MCP

Puedes conectarte a múltiples servidores MCP incluyendo varios objetos en el array mcp_servers:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Usa herramientas de mcp-server-1 y mcp-server-2 para completar esta tarea"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ]
}

Autenticación

Para los servidores MCP que requieren autenticación OAuth, necesitarás obtener un token de acceso. La versión beta del conector MCP admite pasar un parámetro authorization_token en la definición del servidor MCP. Se espera que los consumidores de la API manejen el flujo OAuth y obtengan el token de acceso antes de realizar la llamada a la API, así como renovar el token según sea necesario.

Obtención de un token de acceso para pruebas

El inspector MCP puede guiarte a través del proceso de obtención de un token de acceso para fines de prueba.

  1. Ejecuta el inspector con el siguiente comando. Necesitas tener Node.js instalado en tu máquina.

    npx @modelcontextprotocol/inspector
    
  2. En la barra lateral de la izquierda, para “Transport type”, selecciona “SSE” o “Streamable HTTP”.

  3. Introduce la URL del servidor MCP.

  4. En el área de la derecha, haz clic en el botón “Open Auth Settings” después de “Need to configure authentication?”.

  5. Haz clic en “Quick OAuth Flow” y autoriza en la pantalla de OAuth.

  6. Sigue los pasos en la sección “OAuth Flow Progress” del inspector y haz clic en “Continue” hasta llegar a “Authentication complete”.

  7. Copia el valor de access_token.

  8. Pégalo en el campo authorization_token en tu configuración del servidor MCP.

Uso del token de acceso

Una vez que hayas obtenido un token de acceso utilizando cualquiera de los flujos OAuth anteriores, puedes usarlo en tu configuración de servidor MCP:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

Para explicaciones detalladas del flujo OAuth, consulta la sección de Autorización en la especificación MCP.