Conector MCP

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 un cliente MCP separado.

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 las herramientas MCP a través de la API de Mensajes
• Configuración flexible de herramientas: Habilita todas las herramientas, crea una lista de permitidos para herramientas específicas o una lista de bloqueados para herramientas no deseadas
• Configuración por herramienta: Configura herramientas individuales con ajustes personalizados
• 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 (admite transportes HTTP Streamable y SSE). Los servidores STDIO locales no se pueden conectar directamente.
• El conector MCP actualmente no es compatible con Amazon Bedrock y Google Vertex.

Uso del conector MCP en la API de Mensajes

El conector MCP utiliza dos componentes:

1. Definición del servidor MCP (array mcp_servers): Define los detalles de conexión del servidor (URL, autenticación)
2. Conjunto de herramientas MCP (array tools): Configura qué herramientas habilitar y cómo configurarlas

Ejemplo básico

Este ejemplo habilita todas las herramientas de un servidor MCP con la configuración predeterminada:

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-11-20" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "What tools do you have available?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ],
    "tools": [
      {
        "type": "mcp_toolset",
        "mcp_server_name": "example-mcp"
      }
    ]
  }'

Configuración del servidor MCP

Cada servidor MCP en el array mcp_servers define los detalles de conexión:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

Descripciones de campos

Configuración del conjunto de herramientas MCP

El MCPToolset vive en el array tools y configura qué herramientas del servidor MCP están habilitadas y cómo deben configurarse.

Estructura básica

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

Descripciones de campos

Opciones de configuración de herramientas

Cada herramienta (ya sea configurada en default_config o en configs) admite los siguientes campos:

Fusión de configuraciones

Los valores de configuración se fusionan con esta precedencia (de mayor a menor):

1. Configuraciones específicas de herramientas en configs
2. default_config a nivel de conjunto
3. Valores predeterminados del sistema

Ejemplo:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": false
    }
  }
}

Resulta en:

• search_events: enabled: false (de configs), defer_loading: true (de default_config)
• Todas las demás herramientas: enabled: true (valor predeterminado del sistema), defer_loading: true (de default_config)

Patrones de configuración comunes

Habilitar todas las herramientas con configuración predeterminada

El patrón más simple: habilitar todas las herramientas de un servidor:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

Lista de permitidos - Habilitar solo herramientas específicas

Establece enabled: false como predeterminado, luego habilita explícitamente herramientas específicas:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}

Lista de bloqueados - Deshabilitar herramientas específicas

Habilita todas las herramientas de forma predeterminada, luego deshabilita explícitamente las herramientas no deseadas:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": {
      "enabled": false
    },
    "share_calendar_publicly": {
      "enabled": false
    }
  }
}

Mixto - Lista de permitidos con configuración por herramienta

Combina la lista de permitidos con configuración personalizada para cada herramienta:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false,
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "enabled": true,
      "defer_loading": false
    },
    "list_events": {
      "enabled": true
    }
  }
}

En este ejemplo:

• search_events está habilitado con defer_loading: false
• list_events está habilitado con defer_loading: true (heredado de default_config)
• Todas las demás herramientas están deshabilitadas

Reglas de validación

La API aplica estas reglas de validación:

• El servidor debe existir: El mcp_server_name en un MCPToolset debe coincidir con un servidor definido en el array mcp_servers
• El servidor debe usarse: Cada servidor MCP definido en mcp_servers debe ser referenciado por exactamente un MCPToolset
• Conjunto de herramientas único por servidor: Cada servidor MCP solo puede ser referenciado por un MCPToolset
• Nombres de herramientas desconocidos: Si un nombre de herramienta en configs no existe en el servidor MCP, se registra una advertencia en el backend pero no se devuelve ningún error (los servidores MCP pueden tener disponibilidad de herramientas dinámica)

Tipos de contenido de respuesta

Cuando Claude usa 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 múltiples definiciones de servidor en mcp_servers y un MCPToolset correspondiente para cada uno en el array tools:

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "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"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

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 gestionen el flujo OAuth y obtengan el token de acceso antes de realizar la llamada a la API, así como actualizar 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 propósitos 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 izquierda, para "Transport type", selecciona "SSE" o "Streamable HTTP".

3. Ingresa la URL del servidor MCP.

4. En el área 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 la configuración de tu servidor MCP.

Uso del token de acceso

Una vez que hayas obtenido un token de acceso usando cualquiera de los flujos OAuth anteriores, puedes usarlo en la configuración de tu 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.

Helpers MCP del lado del cliente (TypeScript)

Si gestionas tu propia conexión de cliente MCP (por ejemplo, con servidores stdio locales, prompts MCP o recursos MCP), el SDK de TypeScript proporciona funciones auxiliares que convierten entre tipos MCP y tipos de la API de Claude. Esto elimina el código de conversión manual cuando se usa el SDK de MCP junto con el SDK de Anthropic.

Instalación

Instala tanto el SDK de Anthropic como el SDK de MCP:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk

Helpers disponibles

Importa los helpers desde el espacio de nombres beta:

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";

Usar herramientas MCP

Convierte herramientas MCP para usar con el ejecutor de herramientas del SDK, que maneja la ejecución de herramientas automáticamente:

import Anthropic from "@anthropic-ai/sdk";
import { mcpTools } from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const anthropic = new Anthropic();

// Connect to an MCP server
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

Usar prompts MCP

Convierte mensajes de prompt MCP al formato de mensaje de la API de Claude:

import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";

const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

Usar recursos MCP

Convierte recursos MCP en bloques de contenido para incluir en mensajes, o en objetos de archivo para subir:

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// As a file upload
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

Manejo de errores

Las funciones de conversión lanzan UnsupportedMCPValueError si un valor MCP no es compatible con la API de Claude. Esto puede ocurrir con tipos de contenido no admitidos, tipos MIME o enlaces de recursos que no son HTTP.

Retención de datos

El Conector MCP no está cubierto por los acuerdos ZDR. Los datos intercambiados con servidores MCP, incluidas las definiciones de herramientas y los resultados de ejecución, se retienen de acuerdo con la política estándar de retención de datos de Anthropic.

Para la elegibilidad ZDR en todas las funciones, consulta API y Retención de Datos.

Guía de migración

Si estás usando el encabezado beta obsoleto mcp-client-2025-04-04, sigue esta guía para migrar a la nueva versión.

Cambios principales

1. Nuevo encabezado beta: Cambia de mcp-client-2025-04-04 a mcp-client-2025-11-20
2. Configuración de herramientas movida: La configuración de herramientas ahora vive en el array tools como objetos MCPToolset, no en la definición del servidor MCP
3. Configuración más flexible: El nuevo patrón admite listas de permitidos, listas de bloqueados y configuración por herramienta

Pasos de migración

Antes (obsoleto):

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

Después (actual):

{
  "model": "claude-opus-4-6",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

Patrones de migración comunes

Versión obsoleta: mcp-client-2025-04-04

La versión anterior del conector MCP incluía la configuración de herramientas directamente en la definición del servidor MCP:

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

Descripciones de campos obsoletos