---
title: Conector MCP
url: https://platform.claude.com/docs/es/agents-and-tools/mcp-connector
description: Conéctate a servidores MCP remotos directamente desde la API de Messages sin un cliente MCP, y permite, bloquea o configura herramientas individuales.
featureMetadata:
status: beta
betaHeader: mcp-client-2025-11-20
zdr: not-eligible
supportedPlatforms:
Claude API: beta
Claude Platform on AWS: beta
Microsoft Foundry: beta
---
La función de conector de Model Context Protocol (MCP) de Claude te permite conectarte a servidores MCP remotos directamente desde la API de Messages sin un cliente MCP separado.
La versión anterior de esta función (`mcp-client-2025-04-04`) está obsoleta. Consulta [Versión obsoleta: mcp-client-2025-04-04](https://platform.claude.com/docs/es/agents-and-tools/mcp-connector#deprecated-version-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 Messages
* **Configuración flexible de herramientas:** Habilita todas las herramientas, permite herramientas específicas mediante una lista de permitidos (allowlist) o bloquea herramientas no deseadas mediante una lista de bloqueados (denylist)
* **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
## Cuándo Claude usa herramientas MCP
Una vez que un servidor MCP está conectado, Claude llama a sus herramientas cuando la solicitud del usuario corresponde a la capacidad descrita de una herramienta, ya sea explícitamente ("busca en Jira los bugs abiertos") o implícitamente ("¿qué está bloqueando el lanzamiento?" con un servidor de Jira conectado).
Claude **no** llama a una herramienta MCP para preguntas de conocimiento general sobre un servicio conectado. Preguntar "¿cómo funcionan las bases de datos de Notion?" con un servidor de Notion conectado se responde directamente; preguntar "¿qué hay en mi base de datos Projects?" activa la herramienta.
Puedes orientar la disposición de Claude a llamar herramientas MCP a través de tu "system prompt" (indicación del sistema). Consulta [Cuándo Claude usa herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/overview#when-claude-uses-tools) para obtener orientación general y ejemplos de redacción.
## Limitaciones
* Del conjunto de funciones de la [especificación de MCP](https://modelcontextprotocol.io/introduction#explore-mcp), actualmente solo se admiten las [llamadas a herramientas](https://modelcontextprotocol.io/docs/concepts/tools).
* El servidor debe estar expuesto públicamente a través de HTTP (admite tanto los transportes Streamable HTTP como SSE). Los servidores STDIO locales no se pueden conectar directamente.
## Uso del conector MCP en la API de Messages
El conector MCP usa 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:
```bash cURL
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-5-5",
"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"
}
]
}'
```
```bash CLI
ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
model: claude-opus-5-5
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
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5-5",
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"}],
betas=["mcp-client-2025-11-20"],
)
print(response)
```
```typescript TypeScript
const anthropic = new Anthropic();
const response = await anthropic.beta.messages.create({
model: "claude-opus-5-5",
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"
}
],
betas: ["mcp-client-2025-11-20"]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1000,
Messages = new List
{
new() { Role = Role.User, Content = "What tools do you have available?" }
},
McpServers = new List
{
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN"
}
},
Tools = new List
{
new BetaMcpToolset("example-mcp")
},
Betas = [AnthropicBeta.McpClient2025_11_20]
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
},
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
}},
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaMCPClient2025_11_20,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaMcpToolset;
// ...
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1000L)
.addUserMessage("What tools do you have available?")
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build())
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addBeta(AnthropicBeta.MCP_CLIENT_2025_11_20)
.build();
BetaMessage response = client.beta().messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->beta->messages->create(
maxTokens: 1000,
messages: [
['role' => 'user', 'content' => 'What tools do you have available?']
],
model: 'claude-opus-5-5',
mcpServers: [
[
'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',
],
],
betas: ['mcp-client-2025-11-20'],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-opus-5-5",
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"
}
],
betas: ["mcp-client-2025-11-20"]
)
puts response
```
## Configuración del servidor MCP
Cada servidor MCP en el array `mcp_servers` define los detalles de conexión:
```json
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Descripciones de los campos
| Propiedad | Tipo | Requerido | Descripción |
| --------------------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | string | Sí | Actualmente solo se admite "url". |
| `url` | string | Sí | La URL del servidor MCP. Debe comenzar con https\://. |
| `name` | string | Sí | Un identificador único para este servidor MCP. Debe ser referenciado por exactamente un MCPToolset en el array `tools`. |
| `authorization_token` | string | No | Token de autorización OAuth si el servidor MCP lo requiere. Consulta [Autenticación](https://platform.claude.com/docs/es/agents-and-tools/mcp-connector#authentication) para saber cómo obtener uno, o la [especificación de MCP](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) para los detalles del protocolo. |
## Configuración del conjunto de herramientas MCP
El MCPToolset se encuentra en el array `tools` y configura qué herramientas del servidor MCP están habilitadas y cómo deben configurarse.
### Estructura básica
```json
{
"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 los campos
| Propiedad | Tipo | Requerido | Descripción |
| ----------------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Sí | Debe ser "mcp\_toolset". |
| `mcp_server_name` | string | Sí | Debe coincidir con un nombre de servidor definido en el array `mcp_servers`. |
| `default_config` | object | No | Configuración predeterminada aplicada a todas las herramientas de este conjunto. Las configuraciones individuales de herramientas en `configs` anulan estos valores predeterminados. |
| `configs` | object | No | Anulaciones de configuración por herramienta. Las claves son nombres de herramientas y los valores son objetos de configuración. |
| `cache_control` | object | No | Configuración del punto de interrupción de caché del [almacenamiento en caché de prompts](https://platform.claude.com/docs/es/build-with-claude/prompt-caching) para este conjunto de herramientas. |
Con el encabezado beta `mcp-client-2026-09-15`, un MCPToolset también acepta `tools`, una copia fijada de la lista de herramientas del servidor. Consulta [Fijar la lista de herramientas de un servidor MCP](https://platform.claude.com/docs/es/agents-and-tools/mcp-connector#pin-mcp-tool-list).
### Opciones de configuración de herramientas
Cada herramienta (ya sea configurada en `default_config` o en `configs`) admite los siguientes campos:
| Propiedad | Tipo | Predeterminado | Descripción |
| --------------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | `true` | Si esta herramienta está habilitada. |
| `defer_loading` | boolean | `false` | Si es true, la descripción de la herramienta no se envía al modelo inicialmente. Se usa con la [herramienta de búsqueda de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool). |
Para ver el directorio completo de herramientas proporcionadas por Anthropic y propiedades opcionales como `defer_loading`, consulta la [Referencia de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference). Para buscar en conjuntos grandes de herramientas, consulta la [herramienta de búsqueda de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool).
### Combinación de configuraciones
Los valores de configuración se combinan con esta precedencia (de mayor a menor):
1. Ajustes específicos de la herramienta en `configs`
2. `default_config` a nivel de conjunto
3. Valores predeterminados del sistema
Ejemplo:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}
```
Da como resultado:
* `search_events`: `enabled: false` (de configs), `defer_loading: true` (de default\_config)
* Todas las demás herramientas: `enabled: true` (predeterminado del sistema), `defer_loading: true` (de default\_config)
## Patrones de configuración comunes
### Habilitar todas las herramientas con la configuración predeterminada
El patrón más simple: habilitar todas las herramientas de un servidor:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### Lista de permitidos: habilitar solo herramientas específicas
Establece `enabled: false` como valor predeterminado y luego habilita explícitamente herramientas específicas:
```json
{
"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 y luego deshabilita explícitamente las herramientas no deseadas. Se recomienda bloquear las herramientas de escritura o destructivas al crear asistentes de solo lectura, o cuando quieras un paso de confirmación humana antes de los cambios de estado:
```json
{
"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 una configuración personalizada para cada herramienta:
```json
{
"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á habilitada con `defer_loading: false`
* `list_events` está habilitada 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 dinámica de herramientas)
## Tipos de contenido de respuesta
Cuando Claude usa herramientas MCP, la respuesta incluye dos nuevos tipos de bloques de contenido:
### Bloque de uso de herramienta MCP
```json
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### Bloque de resultado de herramienta MCP
```json
{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
```
## Fijar la lista de herramientas de un servidor MCP (beta)
Un servidor MCP puede cambiar sus herramientas en cualquier momento. El encabezado beta `mcp-client-2026-09-15` registra la lista de herramientas que devuelve cada servidor y te permite fijarla, de modo que un servidor que cambia sus herramientas no cambie lo que Claude ve a mitad de una conversación. Incluye todo lo que hace `mcp-client-2025-11-20`, así que envíalo en lugar de ese encabezado. Está disponible en la Claude API.
Cuando la API le pide a un servidor MCP sus herramientas mientras produce una respuesta, la respuesta comienza con un bloque `mcp_tool_listing` para ese servidor, un bloque por cada servidor al que consultó:
```json
{
"type": "mcp_tool_listing",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
Si tu código lee `content[0]`, omite estos bloques. Envía de vuelta el mensaje del asistente sin cambios, incluidos los bloques `mcp_tool_listing`, y sigue enviando `mcp-client-2026-09-15` en cada solicitud que contenga uno. Las solicitudes posteriores usan entonces la lista registrada para ese servidor en lugar de volver a consultarlo.
Para fijar una lista tú mismo, copia el `tools` de un bloque en el campo `tools` del MCPToolset de ese servidor. La API entonces no le pide al servidor sus herramientas, y las herramientas del conjunto son exactamente esas entradas, con `default_config` y `configs` aplicados:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": "echo",
"description": "Returns the text it receives.",
"input_schema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
}
}
]
}
```
Cada entrada en `tools` contiene el `name` de la herramienta tal como lo lista el servidor (sin el nombre del servidor), su `description` y su `input_schema`.
El siguiente ejemplo envía una solicitud con un conjunto de herramientas sin fijar, copia la lista devuelta en el campo `tools` del conjunto de herramientas y vuelve a enviar la solicitud. La segunda respuesta no tiene ningún bloque `mcp_tool_listing`, porque la API no consulta al servidor:
```bash cURL
BODY='{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"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"
}
],
"messages": [
{
"role": "user",
"content": "What tools do you have available?"
}
]
}'
# Primera solicitud: el conjunto de herramientas no está fijado, así que la API le pide al servidor
# sus herramientas y la respuesta comienza con un bloque mcp_tool_listing.
# tee muestra la respuesta en stderr mientras la variable la captura.
FIRST=$(curl -sS 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-2026-09-15" \
-d "$BODY" | tee /dev/stderr)
# Fija la lista: copia las herramientas del bloque en el conjunto de herramientas. La API usa
# exactamente estas entradas y no vuelve a consultar al servidor.
TOOLS=$(jq '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$FIRST")
PINNED=$(jq --argjson tools "$TOOLS" '.tools[0].tools = $tools' <<<"$BODY")
# Con un conjunto de herramientas fijado, la respuesta no tiene bloque mcp_tool_listing.
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-2026-09-15" \
-d "$PINNED"
```
```bash CLI
request=$(cat <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
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
messages:
- role: user
content: What tools do you have available?
YAML
)
# Primera solicitud: el conjunto de herramientas no está fijado, así que la API le pide al servidor
# sus herramientas y la respuesta empieza con un bloque mcp_tool_listing.
# tee muestra la respuesta en stderr mientras la variable la captura.
first=$(ant beta:messages create --beta mcp-client-2026-09-15 --format json \
<<<"$request" | tee /dev/stderr)
tools=$(jq -c '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$first")
# Fija la lista: copia las herramientas del bloque al conjunto de herramientas. La opción --tool
# reemplaza el arreglo tools del cuerpo. La API usa exactamente estas entradas y
# no vuelve a consultar al servidor, así que la respuesta no tiene bloque mcp_tool_listing.
ant beta:messages create --beta mcp-client-2026-09-15 \
--tool "{type: mcp_toolset, mcp_server_name: example-mcp, tools: $tools}" \
<<<"$request"
```
```python Python
from anthropic.types.beta import (
BetaMessageParam,
BetaRequestMCPServerURLDefinitionParam,
)
client = anthropic.Anthropic()
mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN",
},
]
messages: list[BetaMessageParam] = [
{"role": "user", "content": "What tools do you have available?"},
]
# Primera solicitud: el toolset no está fijado, así que la API le pide al servidor
# sus herramientas y la respuesta empieza con un bloque mcp_tool_listing.
first = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
messages=messages,
)
listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])
# Fija la lista: copia las herramientas del bloque en el toolset. La API usa
# exactamente estas entradas y no vuelve a consultar al servidor.
second = client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
betas=["mcp-client-2026-09-15"],
mcp_servers=mcp_servers,
tools=[
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"tools": [
{
"name": tool.name,
"description": tool.description,
"input_schema": tool.input_schema,
}
for tool in listing.tools
],
},
],
messages=messages,
)
# Con un toolset fijado, la respuesta no tiene ningún bloque mcp_tool_listing.
print([block.type for block in second.content])
```
```typescript TypeScript
const client = new Anthropic();
const mcpServers: Anthropic.Beta.BetaRequestMCPServerURLDefinition[] = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
];
const messages: Anthropic.Beta.BetaMessageParam[] = [
{ role: "user", content: "What tools do you have available?" }
];
// Primera solicitud: el toolset no está fijado, así que la API le pide al servidor
// sus herramientas y la respuesta empieza con un bloque mcp_tool_listing.
const first = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages
});
const listing = first.content.find((block) => block.type === "mcp_tool_listing");
if (!listing) {
throw new Error("The response has no mcp_tool_listing block.");
}
console.log(listing.tools.map((tool) => tool.name));
// Fija la lista: copia las herramientas del bloque en el toolset. La API usa
// exactamente estas entradas y no vuelve a consultar al servidor.
const second = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools
}
],
messages
});
// Con un toolset fijado, la respuesta no incluye ningún bloque mcp_tool_listing.
console.log(second.content.map((block) => block.type));
```
```csharp C#
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
AnthropicClient client = new();
List mcpServers =
[
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN",
},
];
List messages =
[
new() { Role = Role.User, Content = "What tools do you have available?" },
];
// Primera solicitud: el toolset no está fijado, así que la API le pide al servidor
// sus herramientas y la respuesta comienza con un bloque mcp_tool_listing.
var first = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools = [new BetaMcpToolset("example-mcp")],
Messages = messages,
});
var listing = first.Content
.Select(block => block.Value)
.OfType()
.First();
Console.WriteLine(string.Join(", ", listing.Tools.Select(tool => tool.Name)));
// Fija la lista: copia las herramientas del bloque en el toolset. La API usa
// exactamente estas entradas y no vuelve a consultar al servidor.
var second = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools =
[
new BetaMcpToolset("example-mcp")
{
Tools =
[
.. listing.Tools.Select(tool => new BetaMcpToolParam
{
Name = tool.Name,
Description = tool.Description,
InputSchema = tool.InputSchema,
}),
],
},
],
Messages = messages,
});
// Con un toolset fijado, la respuesta no incluye ningún bloque mcp_tool_listing.
Console.WriteLine(string.Join(", ", second.Content.Select(block => block.Type)));
```
```go Go
client := anthropic.NewClient()
mcpServers := []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
}
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
}
// Primera solicitud: el toolset no está fijado, así que la API le pide al servidor
// sus herramientas y la respuesta empieza con un bloque mcp_tool_listing.
first, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{MCPServerName: "example-mcp"}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
var listing anthropic.BetaMCPToolListingBlock
for _, block := range first.Content {
if listingBlock, ok := block.AsAny().(anthropic.BetaMCPToolListingBlock); ok {
listing = listingBlock
break
}
}
// Fija la lista: copia las herramientas del bloque en el toolset. La API usa
// exactamente estas entradas y no vuelve a consultar al servidor.
var toolNames []string
var pinnedTools []anthropic.BetaMCPToolParam
for _, tool := range listing.Tools {
toolNames = append(toolNames, tool.Name)
pinnedTools = append(pinnedTools, anthropic.BetaMCPToolParam{
Name: tool.Name,
Description: anthropic.String(tool.Description),
InputSchema: tool.InputSchema,
})
}
fmt.Println(toolNames)
second, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
Tools: pinnedTools,
}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
// Con un toolset fijado, la respuesta no incluye ningún bloque mcp_tool_listing.
var blockTypes []string
for _, block := range second.Content {
blockTypes = append(blockTypes, block.Type)
}
fmt.Println(blockTypes)
```
```java Java
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMcpTool;
import com.anthropic.models.beta.messages.BetaMcpToolListingBlock;
import com.anthropic.models.beta.messages.BetaMcpToolset;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
import com.anthropic.models.beta.messages.MessageCreateParams;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BetaRequestMcpServerUrlDefinition mcpServer = BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build();
// Primera solicitud: el toolset no está fijado, así que la API le pide al servidor
// sus herramientas y la respuesta empieza con un bloque mcp_tool_listing.
BetaMessage first = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addUserMessage("What tools do you have available?")
.build());
BetaMcpToolListingBlock listing = first.content().stream()
.flatMap(block -> block.mcpToolListing().stream())
.findFirst()
.orElseThrow();
IO.println(listing.tools().stream().map(BetaMcpTool::name).toList());
// Fija la lista: copia las herramientas del bloque en el toolset. La API usa
// exactamente estas entradas y no vuelve a consultar al servidor.
BetaMessage second = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.tools(listing.tools().stream().map(BetaMcpTool::toParam).toList())
.build())
.addUserMessage("What tools do you have available?")
.build());
// Con un toolset fijado, la respuesta no tiene bloque mcp_tool_listing.
IO.println(second.content().stream()
.map(block -> block.type().asString())
.toList());
}
```
```php PHP
use Anthropic\Beta\AnthropicBeta;
use Anthropic\Beta\Messages\BetaMCPTool;
use Anthropic\Beta\Messages\BetaMCPToolListingBlock;
// ...
$client = new Client();
$mcpServers = [
[
'type' => 'url',
'url' => 'https://example-server.modelcontextprotocol.io/sse',
'name' => 'example-mcp',
'authorization_token' => 'YOUR_TOKEN',
],
];
$messages = [['role' => 'user', 'content' => 'What tools do you have available?']];
// Primera solicitud: el toolset no está fijado, así que la API le pide al servidor
// sus herramientas y la respuesta comienza con un bloque mcp_tool_listing.
$first = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [['type' => 'mcp_toolset', 'mcp_server_name' => 'example-mcp']],
messages: $messages,
);
$listing = array_find($first->content, fn ($block) => $block instanceof BetaMCPToolListingBlock);
echo json_encode(array_map(fn (BetaMCPTool $tool) => $tool->name, $listing->tools)), PHP_EOL;
// Fija la lista: copia las herramientas del bloque en el toolset. La API usa
// exactamente estas entradas y no vuelve a consultar al servidor.
$second = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [
[
'type' => 'mcp_toolset',
'mcp_server_name' => 'example-mcp',
'tools' => array_map(
fn (BetaMCPTool $tool) => [
'name' => $tool->name,
'description' => $tool->description,
'input_schema' => $tool->inputSchema,
],
$listing->tools,
),
],
],
messages: $messages,
);
// Con un toolset fijado, la respuesta no incluye ningún bloque mcp_tool_listing.
echo json_encode(array_map(fn ($block) => $block->type, $second->content)), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
mcp_servers = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
]
messages = [{ role: "user", content: "What tools do you have available?" }]
# Primera solicitud: el toolset no está fijado, así que la API le pide al servidor
# sus herramientas y la respuesta empieza con un bloque mcp_tool_listing.
first = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages:
)
listing = first.content.find { it.is_a?(Anthropic::Beta::BetaMCPToolListingBlock) }
puts listing.tools.map(&:name).inspect
# Fija la lista: copia las herramientas del bloque en el toolset. La API usa
# exactamente estas entradas y no vuelve a consultar al servidor.
second = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools.map(&:to_h)
}
],
messages:
)
# Con un toolset fijado, la respuesta no incluye ningún bloque mcp_tool_listing.
puts second.content.map(&:type).inspect
```
Si además usas el encabezado beta `inline-tools-2026-09-15`, puedes agregar un servidor MCP a mitad de una conversación. Consulta [Agregar un servidor MCP a mitad de la conversación](https://platform.claude.com/docs/es/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta).
## 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`:
```json
{
"model": "claude-opus-5-5",
"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
}
}
]
}
```
Con muchas herramientas disponibles, Claude selecciona basándose en los nombres y descripciones de las herramientas. Las descripciones de herramientas claras y específicas mejoran la precisión de la selección. Para conjuntos grandes de herramientas (docenas de herramientas en varios servidores), considera habilitar [`defer_loading`](https://platform.claude.com/docs/es/agents-and-tools/mcp-connector#tool-configuration-options) con la [herramienta de búsqueda de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-search-tool) para que solo se muestren las herramientas relevantes por consulta.
## Autenticación
Para los servidores MCP que requieren autenticación OAuth, necesitarás obtener un token de acceso. La 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, y que actualicen el token según sea necesario.
### Obtener un token de acceso para pruebas
El inspector de MCP puede guiarte a través del proceso de obtención de un token de acceso con fines de prueba.
1. Ejecuta el inspector con el siguiente comando. Necesitas tener Node.js instalado en tu máquina.
```bash
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 **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` de 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:
```json
{
"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](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) en la especificación de MCP.
## Helpers de MCP del lado del cliente
Si administras tu propia conexión de cliente MCP (por ejemplo, con servidores stdio locales, prompts de MCP o recursos de MCP), el SDK proporciona "helpers" (funciones auxiliares) que convierten entre tipos de MCP y tipos de la API de Claude. Esto elimina el código de conversión manual cuando usas un SDK de MCP para tu lenguaje (por ejemplo, el [SDK de MCP para TypeScript](https://github.com/modelcontextprotocol/typescript-sdk)) junto con el SDK de Anthropic.
Usa el [parámetro de API `mcp_servers`](https://platform.claude.com/docs/es/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api) cuando tengas servidores remotos accesibles por URL y solo necesites compatibilidad con herramientas. Usa los helpers del lado del cliente cuando necesites servidores locales, prompts, recursos o más control sobre la conexión con el SDK base.
### Instalación
Instala tanto el SDK de Anthropic como el SDK de MCP:
Los helpers de MCP se incluyen en el extra `mcp`, que requiere Python 3.10 o posterior:
```bash
pip install "anthropic[mcp]"
```
```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```
Los helpers se encuentran en el paquete independiente `Anthropic.Mcp`; el cliente MCP en sí proviene del [paquete oficial ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol):
```bash
dotnet add package Anthropic.Mcp
dotnet add package ModelContextProtocol
```
Los helpers se encuentran en el subpaquete `mcp` del SDK de Go, que se basa en el [SDK de MCP para Go](https://github.com/modelcontextprotocol/go-sdk):
```bash
go get github.com/anthropics/anthropic-sdk-go/mcp
```
Los helpers se encuentran en el artefacto independiente `anthropic-java-mcp`, que requiere Java 17 o posterior (el SDK base es compatible con Java 8). Agrégalo junto con la dependencia base `anthropic-java`:
```kotlin
implementation("com.anthropic:anthropic-java:2.73.0")
implementation("com.anthropic:anthropic-java-mcp:2.73.0")
```
```xml
com.anthropic
anthropic-java
2.73.0
com.anthropic
anthropic-java-mcp
2.73.0
```
Los helpers usan el [SDK oficial de MCP para PHP](https://packagist.org/packages/mcp/sdk):
```bash
composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" "mcp/sdk"
```
Los helpers usan la [gema oficial `mcp`](https://rubygems.org/gems/mcp):
```bash
bundle add anthropic mcp
```
### Helpers disponibles
Importa los helpers para tu lenguaje:
```python Python
from anthropic.lib.tools.mcp import (
async_mcp_tool,
mcp_message,
mcp_resource_to_content,
mcp_resource_to_file,
)
```
```typescript TypeScript
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
```
```go Go
import (
"github.com/anthropics/anthropic-sdk-go/mcp"
)
```
```java Java
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
```
```ruby Ruby
require "anthropic"
# Los helpers se exponen en el módulo Anthropic::Mcp
```
| Helper | Descripción |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `async_mcp_tool(tool, mcp_client)` (typescript: `mcpTools(tools, mcpClient)`; csharp: `BetaMcp.ListToolsAsync(mcpClient)`; go: `mcp.NewBetaTools(tools, session)`; java: `BetaMcp.mcpTools(tools, mcpClient)`; php: `BetaMcp::tools($tools, $mcp)`; ruby: `Anthropic::Mcp.tools(tools, mcp_client)`) | Convierte herramientas MCP en herramientas de la API de Claude para usarlas con `client.beta.messages.tool_runner()` (typescript: `client.beta.messages.toolRunner()`; java: `client.beta().messages().toolRunner()`; php: `$client->beta->messages->toolRunner()`; csharp: `client.Beta.Messages.ToolRunner()`; go: `client.Beta.Messages.NewToolRunner()`) |
| `mcp_message(message)` (typescript: `mcpMessages(messages)`; csharp: `BetaMcp.Messages(messages)`; go: `mcp.ToMessage(message)`; java: `BetaMcp.mcpMessages(messages)`; php: `BetaMcp::message($message)`; ruby: `Anthropic::Mcp.message(message)`) | Convierte mensajes de prompts de MCP al formato de mensaje de la API de Claude |
| `mcp_resource_to_content(resource)` (typescript: `mcpResourceToContent(resource)`; csharp: `BetaMcp.ResourceToContent(resource)`; go: `mcp.ResourceToBlock(resource)`; java: `BetaMcp.mcpResourceContents(resource)`; php: `BetaMcp::resourceToContent($resource)`; ruby: `Anthropic::Mcp.resource_to_contents(resource)`) | Convierte un recurso de MCP en un bloque de contenido de la API de Claude |
| `mcp_resource_to_file(resource)` (typescript: `mcpResourceToFile(resource)`; csharp: `BetaMcp.ResourceToFile(resource)`; go: `mcp.ResourceToFile(resource)`; java: `BetaMcp.mcpResourceFiles(resource)`; php: `BetaMcp::resourceToFile($resource)`; ruby: `Anthropic::Mcp.resource_to_files(resource)`) | Convierte un recurso de MCP en un objeto de archivo para cargarlo |
### Usar herramientas MCP
Convierte herramientas MCP para usarlas con el [ejecutor de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-runner) del SDK, que maneja la ejecución de herramientas automáticamente:
```python Python
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client
client = AsyncAnthropic()
async def main() -> None:
# Conectarse a un servidor MCP
server_params = StdioServerParameters(command="mcp-server")
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as mcp_client:
await mcp_client.initialize()
# Listar las herramientas y convertirlas para la API de Claude
tools_result = await mcp_client.list_tools()
runner = client.beta.messages.tool_runner(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "What tools do you have available?"},
],
tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
)
final_message = await runner.until_done()
print(final_message)
asyncio.run(main())
```
```typescript TypeScript
import {
mcpTools,
type MCPCallToolResultLike,
type MCPClientLike
} 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();
// Conéctate a un servidor MCP
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);
// Lista las herramientas y conviértelas para la API de Claude
const { tools } = await mcpClient.listTools();
// El tipo de retorno de callTool del SDK de MCP aún incluye una forma de resultado heredada que
// mcpTools no acepta; acótalo. Elimina esto cuando MCPClientLike se amplíe.
const mcpClientForTools: MCPClientLike = {
callTool: (params) => mcpClient.callTool(params) as Promise
};
const finalMessage = await anthropic.beta.messages.toolRunner({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: mcpTools(tools, mcpClientForTools)
});
console.log(finalMessage);
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
using Anthropic.Models.Beta.Messages;
using ModelContextProtocol.Client;
using Messages = Anthropic.Models.Messages;
var anthropic = new AnthropicClient();
// Conectarse a un servidor MCP
await using var mcpClient = await McpClient.CreateAsync(
new StdioClientTransport(new StdioClientTransportOptions { Command = "mcp-server" })
);
// Listar las herramientas y convertirlas para la API de Claude
var tools = await BetaMcp.ListToolsAsync(mcpClient);
var runner = anthropic.Beta.Messages.ToolRunner(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "What tools do you have available?",
},
],
},
tools
);
var finalMessage = await runner.RunUntilDoneAsync();
Console.WriteLine(finalMessage);
```
```go Go
import (
// ...
// ...
"github.com/anthropics/anthropic-sdk-go/mcp"
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)
func main() {
client := anthropic.NewClient()
ctx := context.Background()
// Conectarse a un servidor MCP
mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "my-client", Version: "1.0.0"}, nil)
session, err := mcpClient.Connect(ctx, &mcpsdk.CommandTransport{Command: exec.Command("mcp-server")}, nil)
if err != nil {
log.Fatal(err)
}
defer session.Close()
// Listar las herramientas y convertirlas para la API de Claude
toolsResult, err := session.ListTools(ctx, nil)
if err != nil {
log.Fatal(err)
}
betaTools, err := mcp.NewBetaTools(toolsResult.Tools, session)
if err != nil {
log.Fatal(err)
}
runner := client.Beta.Messages.NewToolRunner(betaTools, anthropic.BetaToolRunnerParams{
BetaMessageNewParams: anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
},
})
finalMessage, err := runner.RunToCompletion(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println(finalMessage.RawJSON())
}
```
```java Java
import com.anthropic.helpers.BetaToolRunner;
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.json.McpJsonDefaults;
import io.modelcontextprotocol.spec.McpSchema;
// ...
void main() throws Exception {
AnthropicClient anthropic = AnthropicOkHttpClient.fromEnv();
// Conectarse a un servidor MCP
StdioClientTransport transport = new StdioClientTransport(
ServerParameters.builder("mcp-server").build(), McpJsonDefaults.getMapper());
try (McpSyncClient mcpClient = McpClient.sync(transport)
.clientInfo(new McpSchema.Implementation("my-client", "1.0.0"))
.build()) {
mcpClient.initialize();
// Listar las herramientas y convertirlas para la API de Claude
List betaTools = BetaMcp.mcpTools(mcpClient.listTools().tools(), mcpClient);
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("What tools do you have available?")
.addTools(betaTools)
.build();
// El runner produce un mensaje por turno del asistente; el último es la respuesta final
BetaToolRunner runner = anthropic.beta().messages().toolRunner(params);
BetaMessage finalMessage = null;
for (BetaMessage message : runner) {
finalMessage = message;
}
IO.println(finalMessage);
}
}
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
use Mcp\Client;
use Mcp\Client\Transport\HttpTransport;
$anthropic = new Anthropic();
// Conéctate a un servidor MCP. El cliente MCP de PHP se conecta por HTTP; apunta esto
// al endpoint de tu servidor.
$mcp = Client::builder()->build();
$mcp->connect(new HttpTransport('http://localhost:8000/mcp'));
// Lista las herramientas y conviértelas para la API de Claude
$runner = $anthropic->beta->messages->toolRunner(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'What tools do you have available?']],
model: 'claude-opus-5-5',
tools: BetaMcp::tools($mcp->listTools()->tools, $mcp),
);
echo $runner->runUntilDone(), "\n";
```
```ruby Ruby
require "mcp"
anthropic = Anthropic::Client.new
# Conectarse a un servidor MCP
transport = MCP::Client::Stdio.new(command: "mcp-server")
mcp_client = MCP::Client.new(transport: transport)
mcp_client.connect
# Listar las herramientas y convertirlas para la API de Claude
runner = anthropic.beta.messages.tool_runner(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: Anthropic::Mcp.tools(mcp_client.tools, mcp_client)
)
final_message = runner.run_until_finished.last
puts final_message
```
### Usar prompts de MCP
Convierte mensajes de prompts de MCP al formato de mensajes de la API de Claude:
```python Python
from anthropic.lib.tools.mcp import mcp_message
prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[mcp_message(message) for message in prompt.messages],
)
print(response)
```
```typescript TypeScript
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-opus-5-5",
max_tokens: 1024,
messages: mcpMessages(messages)
});
console.log(response);
```
```csharp C#
var prompt = await mcpClient.GetPromptAsync("my-prompt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = BetaMcp.Messages(prompt.Messages),
}
);
Console.WriteLine(response);
```
```go Go
prompt, err := session.GetPrompt(ctx, &mcpsdk.GetPromptParams{Name: "my-prompt"})
if err != nil {
log.Fatal(err)
}
messages := make([]anthropic.BetaMessageParam, 0, len(prompt.Messages))
for _, promptMessage := range prompt.Messages {
message, err := mcp.ToMessage(promptMessage)
if err != nil {
log.Fatal(err)
}
messages = append(messages, message)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
McpSchema.GetPromptResult prompt = mcpClient.getPrompt(
new McpSchema.GetPromptRequest("my-prompt", Map.of()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(BetaMcp.mcpMessages(prompt.messages()))
.build());
IO.println(response);
```
```php PHP
$prompt = $mcp->getPrompt('my-prompt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: array_map(BetaMcp::message(...), $prompt->messages),
model: 'claude-opus-5-5',
);
echo $response, "\n";
```
```ruby Ruby
prompt = mcp_client.get_prompt(name: "my-prompt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: prompt["messages"].map { |message| Anthropic::Mcp.message(message) }
)
puts response
```
### Usar recursos de MCP
Convierte recursos de MCP en bloques de contenido para incluir en mensajes, o en objetos de archivo para cargar:
```python Python
from anthropic.lib.tools.mcp import (
mcp_resource_to_content,
mcp_resource_to_file,
)
# Como bloque de contenido en un mensaje
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
mcp_resource_to_content(resource),
{"type": "text", "text": "Summarize this document"},
],
}
],
)
print(response)
# Como carga de archivo
file_resource = await mcp_client.read_resource(
uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)
```
```typescript TypeScript
import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";
// Como bloque de contenido en un mensaje
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
const response = await anthropic.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
mcpResourceToContent(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
});
console.log(response);
// Como carga de archivo
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
const uploaded = await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });
console.log(uploaded.id);
```
```csharp C#
// Como bloque de contenido en un mensaje
var resource = await mcpClient.ReadResourceAsync("file:///path/to/doc.txt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = new BetaMessageParamContent(
[
BetaMcp.ResourceToContent(resource),
new BetaTextBlockParam { Text = "Summarize this document" },
]
),
},
],
}
);
Console.WriteLine(response);
// Como carga de archivo
var fileResource = await mcpClient.ReadResourceAsync("file:///path/to/data.json");
var (filename, data, mediaType) = BetaMcp.ResourceToFile(fileResource);
// Construye la parte del archivo explícitamente para que el nombre y el tipo MIME del recurso
// se conserven en la carga.
var file = new BinaryContent { Stream = new MemoryStream(data), FileName = filename };
if (mediaType is not null)
{
file.ContentType = new(mediaType);
}
var uploaded = await anthropic.Files.Upload(new FileUploadParams { File = file });
Console.WriteLine(uploaded.ID);
```
```go Go
// Como bloque de contenido en un mensaje
resource, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/doc.txt"})
if err != nil {
log.Fatal(err)
}
block, err := mcp.ResourceToBlock(resource)
if err != nil {
log.Fatal(err)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
// ResourceToBlock devuelve la unión de contenido de tool-result; el contenido
// del mensaje es un tipo de unión distinto, así que reenvuelve las variantes compartidas
// (mcp.ToMessage hace lo mismo internamente).
anthropic.BetaContentBlockParamUnion{
OfText: block.OfText,
OfImage: block.OfImage,
OfDocument: block.OfDocument,
},
anthropic.NewBetaTextBlock("Summarize this document"),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
// Como carga de archivo
fileResult, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/data.json"})
if err != nil {
log.Fatal(err)
}
fileReader, err := mcp.ResourceToFile(fileResult)
if err != nil {
log.Fatal(err)
}
uploaded, err := client.Files.Upload(ctx, anthropic.FileUploadParams{File: fileReader})
if err != nil {
log.Fatal(err)
}
fmt.Println(uploaded.ID)
```
```java Java
// Como bloque de contenido en un mensaje
McpSchema.ReadResourceResult resource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/doc.txt"));
List content =
new ArrayList<>(BetaMcp.mcpResourceContents(resource));
content.add(BetaContentBlockParam.ofText(
BetaTextBlockParam.builder().text("Summarize this document").build()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessageOfBetaContentBlockParams(content)
.build());
IO.println(response);
// Como carga de archivo
McpSchema.ReadResourceResult fileResource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/data.json"));
McpResourceFile resourceFile = BetaMcp.mcpResourceFiles(fileResource).getFirst();
// Construye la parte del archivo explícitamente para que el nombre de archivo y el tipo MIME del recurso
// se conserven en la carga.
MultipartField.Builder fileField = MultipartField.builder()
.value(new ByteArrayInputStream(resourceFile.content()))
.filename(resourceFile.filename());
if (resourceFile.mimeType() != null) {
fileField.contentType(resourceFile.mimeType());
}
var uploaded = anthropic.files().upload(FileUploadParams.builder()
.file(fileField.build())
.build());
IO.println(uploaded.id());
```
```php PHP
// Como bloque de contenido en un mensaje
$resource = $mcp->readResource('file:///path/to/doc.txt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
BetaMcp::resourceToContent($resource),
['type' => 'text', 'text' => 'Summarize this document'],
],
],
],
model: 'claude-opus-5-5',
);
echo $response, "\n";
// Como carga de archivo
$fileResource = $mcp->readResource('file:///path/to/data.json');
$file = $anthropic->files->upload(file: BetaMcp::resourceToFile($fileResource));
echo $file->id, "\n";
```
```ruby Ruby
# Como bloque de contenido en un mensaje
resource = mcp_client.read_resource(uri: "file:///path/to/doc.txt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
*Anthropic::Mcp.resource_to_contents(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
)
puts response
# Como carga de archivo
file_resource = mcp_client.read_resource(uri: "file:///path/to/data.json")
file = Anthropic::Mcp.resource_to_files(file_resource).first
uploaded_file = anthropic.files.upload(file: file)
puts uploaded_file.id
```
### Manejo de errores
Las funciones de conversión fallan con `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) si la API de Claude no admite un valor de MCP (se lanza como excepción o, en Go, se devuelve como error). Esto puede ocurrir con tipos de contenido, tipos MIME o enlaces a recursos no admitidos (resuelve los enlaces a recursos con tu cliente MCP antes de convertirlos).
## Solicitudes por lotes
Puedes incluir `mcp_servers` en solicitudes de la [API de Message Batches](https://platform.claude.com/docs/es/build-with-claude/batch-processing). Las llamadas a herramientas MCP a través de la API de Batches tienen el mismo precio que las de las solicitudes normales de la API de Messages.
## Retención de datos
El conector MCP no está cubierto por los acuerdos de ZDR. Los datos intercambiados con los 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 conocer la elegibilidad de ZDR en todas las funciones, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention).
## 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. **La configuración de herramientas se movió:** La configuración de herramientas ahora se encuentra 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):**
```json
{
"model": "claude-opus-5-5",
"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):**
```json
{
"model": "claude-opus-5-5",
"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
| Patrón anterior | Patrón nuevo |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Sin `tool_configuration` (todas las herramientas habilitadas) | MCPToolset sin `default_config` ni `configs` |
| `tool_configuration.enabled: false` | MCPToolset con `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset con `default_config.enabled: false` y herramientas específicas habilitadas en `configs` |
## Versión obsoleta: mcp-client-2025-04-04
Esta versión está obsoleta. Migra a `mcp-client-2025-11-20` usando la [guía de migración](https://platform.claude.com/docs/es/agents-and-tools/mcp-connector#migration-guide) anterior.
La versión anterior del conector MCP incluía la configuración de herramientas directamente en la definición del servidor MCP:
```json
{
"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
| Propiedad | Tipo | Descripción |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `tool_configuration` | object | **Obsoleto:** Usa MCPToolset en el array `tools` en su lugar |
| `tool_configuration.enabled` | boolean | **Obsoleto:** Usa `default_config.enabled` en MCPToolset |
| `tool_configuration.allowed_tools` | array | **Obsoleto:** Usa el patrón de lista de permitidos con `configs` en MCPToolset |