---
title: Conector MCP
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector
description: Conecte-se a servidores MCP remotos diretamente da API Messages sem um cliente MCP e crie listas de permissão, listas de bloqueio ou configure ferramentas individuais.
featureMetadata:
status: beta
betaHeader: mcp-client-2025-11-20
zdr: not-eligible
supportedPlatforms:
Claude API: beta
Claude Platform on AWS: beta
Microsoft Foundry: beta
---
O recurso de conector do "Model Context Protocol", ou MCP, do Claude permite que você se conecte a servidores MCP remotos diretamente da API Messages sem um cliente MCP separado.
A versão anterior deste recurso (`mcp-client-2025-04-04`) está descontinuada. Consulte [Versão descontinuada: mcp-client-2025-04-04](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04).
## Principais recursos
* **Integração direta com a API:** Conecte-se a servidores MCP sem implementar um cliente MCP
* **Suporte a chamadas de ferramentas:** Acesse ferramentas MCP por meio da API Messages
* **Configuração flexível de ferramentas:** Habilite todas as ferramentas, crie uma lista de permissão de ferramentas específicas ou uma lista de bloqueio de ferramentas indesejadas
* **Configuração por ferramenta:** Configure ferramentas individuais com definições personalizadas
* **Autenticação OAuth:** Suporte a tokens OAuth Bearer para servidores autenticados
* **Múltiplos servidores:** Conecte-se a múltiplos servidores MCP em uma única requisição
## Quando o Claude usa ferramentas MCP
Depois que um servidor MCP é conectado, o Claude chama suas ferramentas quando a solicitação do usuário corresponde à capacidade descrita de uma ferramenta, seja explicitamente ("pesquise no Jira por bugs abertos") ou implicitamente ("o que está bloqueando o lançamento?" com um servidor Jira anexado).
O Claude **não** chama uma ferramenta MCP para perguntas de conhecimento geral sobre um serviço conectado. Perguntar "como funcionam os bancos de dados do Notion?" com um servidor Notion anexado é respondido diretamente; perguntar "o que há no meu banco de dados Projects?" aciona a ferramenta.
Você pode orientar a prontidão com que o Claude chama ferramentas MCP por meio do seu prompt do sistema. Consulte [Quando o Claude usa ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview#when-claude-uses-tools) para orientações gerais e exemplos de formulações.
## Limitações
* Do conjunto de recursos da [especificação MCP](https://modelcontextprotocol.io/introduction#explore-mcp), apenas [chamadas de ferramentas](https://modelcontextprotocol.io/docs/concepts/tools) são suportadas atualmente.
* O servidor deve estar exposto publicamente via HTTP (suporta os transportes Streamable HTTP e SSE). Servidores STDIO locais não podem ser conectados diretamente.
## Usando o conector MCP na API Messages
O conector MCP usa dois componentes:
1. **Definição do servidor MCP** (array `mcp_servers`): Define os detalhes de conexão do servidor (URL, autenticação)
2. **Conjunto de ferramentas MCP** (array `tools`): Configura quais ferramentas habilitar e como configurá-las
### Exemplo básico
Este exemplo habilita todas as ferramentas de um servidor MCP com a configuração padrão:
```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
```
## Configuração do servidor MCP
Cada servidor MCP no array `mcp_servers` define os detalhes de conexão:
```json
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Descrições dos campos
| Propriedade | Tipo | Obrigatório | Descrição |
| --------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | string | Sim | Atualmente apenas "url" é suportado. |
| `url` | string | Sim | A URL do servidor MCP. Deve começar com https\://. |
| `name` | string | Sim | Um identificador único para este servidor MCP. Deve ser referenciado por exatamente um MCPToolset no array `tools`. |
| `authorization_token` | string | Não | Token de autorização OAuth, se exigido pelo servidor MCP. Consulte [Autenticação](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector#authentication) para saber como obter um, ou a [especificação MCP](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) para detalhes do protocolo. |
## Configuração do conjunto de ferramentas MCP
O MCPToolset fica no array `tools` e configura quais ferramentas do servidor MCP estão habilitadas e como devem ser configuradas.
### Estrutura 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
}
}
}
```
### Descrições dos campos
| Propriedade | Tipo | Obrigatório | Descrição |
| ----------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | string | Sim | Deve ser "mcp\_toolset". |
| `mcp_server_name` | string | Sim | Deve corresponder a um nome de servidor definido no array `mcp_servers`. |
| `default_config` | object | Não | Configuração padrão aplicada a todas as ferramentas deste conjunto. Configurações individuais de ferramentas em `configs` substituem esses padrões. |
| `configs` | object | Não | Substituições de configuração por ferramenta. As chaves são nomes de ferramentas e os valores são objetos de configuração. |
| `cache_control` | object | Não | Configuração de ponto de interrupção de cache do [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) para este conjunto de ferramentas. |
Com o cabeçalho beta `mcp-client-2026-09-15`, um MCPToolset também aceita `tools`, uma cópia fixada da lista de ferramentas do servidor. Consulte [Fixar a lista de ferramentas de um servidor MCP](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector#pin-mcp-tool-list).
### Opções de configuração de ferramentas
Cada ferramenta (seja configurada em `default_config` ou em `configs`) suporta os seguintes campos:
| Propriedade | Tipo | Padrão | Descrição |
| --------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | `true` | Se esta ferramenta está habilitada. |
| `defer_loading` | boolean | `false` | Se true, a descrição da ferramenta não é enviada ao modelo inicialmente. Usado com a [ferramenta de busca de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool). |
Para o diretório completo de ferramentas fornecidas pela Anthropic e propriedades opcionais como `defer_loading`, consulte a [Referência de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference). Para pesquisar em grandes conjuntos de ferramentas, consulte a [ferramenta de busca de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool).
### Mesclagem de configuração
Os valores de configuração são mesclados com esta precedência (da mais alta para a mais baixa):
1. Configurações específicas da ferramenta em `configs`
2. `default_config` no nível do conjunto
3. Padrões do sistema
Exemplo:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}
```
Resulta em:
* `search_events`: `enabled: false` (de configs), `defer_loading: true` (de default\_config)
* Todas as outras ferramentas: `enabled: true` (padrão do sistema), `defer_loading: true` (de default\_config)
## Padrões comuns de configuração
### Habilitar todas as ferramentas com a configuração padrão
O padrão mais simples: habilitar todas as ferramentas de um servidor:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}
```
### Lista de permissão: habilitar apenas ferramentas específicas
Defina `enabled: false` como padrão e, em seguida, habilite explicitamente ferramentas 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 bloqueio: desabilitar ferramentas específicas
Habilite todas as ferramentas por padrão e, em seguida, desabilite explicitamente as ferramentas indesejadas. Colocar ferramentas de escrita ou destrutivas em uma lista de bloqueio é recomendado ao criar assistentes somente leitura, ou quando você deseja uma etapa de confirmação humana antes de alterações de estado:
```json
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}
```
### Misto: lista de permissão com configuração por ferramenta
Combine a lista de permissão com configuração personalizada para cada ferramenta:
```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
}
}
}
```
Neste exemplo:
* `search_events` está habilitada com `defer_loading: false`
* `list_events` está habilitada com `defer_loading: true` (herdado de default\_config)
* Todas as outras ferramentas estão desabilitadas
## Regras de validação
A API aplica estas regras de validação:
* **O servidor deve existir:** O `mcp_server_name` em um MCPToolset deve corresponder a um servidor definido no array `mcp_servers`
* **O servidor deve ser usado:** Todo servidor MCP definido em `mcp_servers` deve ser referenciado por exatamente um MCPToolset
* **Conjunto de ferramentas único por servidor:** Cada servidor MCP só pode ser referenciado por um MCPToolset
* **Nomes de ferramentas desconhecidos:** Se um nome de ferramenta em `configs` não existir no servidor MCP, um aviso é registrado no backend, mas nenhum erro é retornado (servidores MCP podem ter disponibilidade dinâmica de ferramentas)
## Tipos de conteúdo da resposta
Quando o Claude usa ferramentas MCP, a resposta inclui dois novos tipos de bloco de conteúdo:
### Bloco de uso de ferramenta MCP
```json
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### Bloco de resultado de ferramenta MCP
```json
{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}
```
## Fixar a lista de ferramentas de um servidor MCP (beta)
Um servidor MCP pode alterar suas ferramentas a qualquer momento. O cabeçalho beta `mcp-client-2026-09-15` registra a lista de ferramentas que cada servidor retorna e permite que você a fixe, para que um servidor que altere suas ferramentas não mude o que o Claude vê no meio de uma conversa. Ele inclui tudo o que `mcp-client-2025-11-20` inclui, então envie-o no lugar desse cabeçalho. Ele está disponível na Claude API.
Quando a API solicita a um servidor MCP suas ferramentas enquanto produz uma resposta, a resposta começa com um bloco `mcp_tool_listing` para esse servidor, um bloco para cada servidor consultado:
```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"]
}
}
]
}
```
Se o seu código lê `content[0]`, ignore esses blocos. Envie a mensagem do assistente de volta sem alterações, incluindo os blocos `mcp_tool_listing`, e continue enviando `mcp-client-2026-09-15` em toda requisição que contenha um deles. As requisições posteriores então usam a lista registrada para esse servidor em vez de consultá-lo novamente.
Para fixar uma lista você mesmo, copie o `tools` de um bloco para o campo `tools` do MCPToolset desse servidor. A API então não solicita ao servidor suas ferramentas, e as ferramentas do toolset são exatamente essas entradas, com `default_config` e `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 em `tools` contém o `name` da ferramenta conforme o servidor a lista (sem o nome do servidor), sua `description` e seu `input_schema`.
O exemplo a seguir envia uma requisição com um toolset não fixado, copia a lista retornada para o campo `tools` do toolset e envia a requisição novamente. A segunda resposta não tem bloco `mcp_tool_listing`, porque a API não consulta o 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?"
}
]
}'
# Primeira requisição: o toolset não está fixado, então a API pede ao servidor
# suas ferramentas e a resposta começa com um bloco mcp_tool_listing.
# o tee mostra a resposta no stderr enquanto a variável a 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)
# Fixe a lista: copie as ferramentas do bloco para o toolset. A API usa
# exatamente essas entradas e não consulta o servidor novamente.
TOOLS=$(jq '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$FIRST")
PINNED=$(jq --argjson tools "$TOOLS" '.tools[0].tools = $tools' <<<"$BODY")
# Com um toolset fixado, a resposta não tem bloco 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
)
# Primeira requisição: o toolset não está fixado, então a API pede ao servidor
# suas ferramentas e a resposta começa com um bloco mcp_tool_listing.
# O tee mostra a resposta no stderr enquanto a variável a 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")
# Fixe a lista: copie as ferramentas do bloco para o toolset. A flag --tool
# substitui o array tools do corpo. A API usa exatamente essas entradas e
# não consulta o servidor de novo, então a resposta não tem bloco 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?"},
]
# Primeira requisição: o toolset não está fixado, então a API pede ao servidor
# suas ferramentas e a resposta começa com um bloco 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])
# Fixe a lista: copie as ferramentas do bloco para o toolset. A API usa
# exatamente essas entradas e não consulta o servidor novamente.
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,
)
# Com um toolset fixado, a resposta não tem bloco 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?" }
];
// Primeira requisição: o toolset não está fixado, então a API pede ao servidor
// suas ferramentas e a resposta começa com um bloco 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));
// Fixe a lista: copie as ferramentas do bloco para o toolset. A API usa
// exatamente essas entradas e não consulta o servidor novamente.
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
});
// Com um toolset fixado, a resposta não tem bloco 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?" },
];
// Primeira requisição: o toolset não está fixado, então a API pede ao servidor
// suas ferramentas e a resposta começa com um bloco 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)));
// Fixe a lista: copie as ferramentas do bloco para o toolset. A API usa
// exatamente essas entradas e não consulta o servidor novamente.
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,
});
// Com um toolset fixado, a resposta não tem bloco 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?")),
}
// Primeira requisição: o toolset não está fixado, então a API pede ao servidor
// as ferramentas dele e a resposta começa com um bloco 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
}
}
// Fixe a lista: copie as ferramentas do bloco para o toolset. A API usa
// exatamente essas entradas e não consulta o servidor novamente.
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)
}
// Com um toolset fixado, a resposta não tem bloco 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();
// Primeira requisição: o toolset não está fixado, então a API pede ao servidor
// suas ferramentas e a resposta começa com um bloco 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());
// Fixe a lista: copie as ferramentas do bloco para o toolset. A API usa
// exatamente essas entradas e não consulta o servidor novamente.
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());
// Com um toolset fixado, a resposta não tem bloco 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?']];
// Primeira requisição: o toolset não está fixado, então a API pede ao servidor
// suas ferramentas e a resposta começa com um bloco 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;
// Fixe a lista: copie as ferramentas do bloco para o toolset. A API usa
// exatamente essas entradas e não consulta o servidor novamente.
$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,
);
// Com um toolset fixado, a resposta não tem bloco 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?" }]
# Primeira requisição: o toolset não está fixado, então a API pede ao servidor
# suas ferramentas e a resposta começa com um bloco 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
# Fixe a lista: copie as ferramentas do bloco para o toolset. A API usa
# exatamente essas entradas e não consulta o servidor novamente.
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:
)
# Com um toolset fixado, a resposta não tem bloco mcp_tool_listing.
puts second.content.map(&:type).inspect
```
Se você também enviar o cabeçalho beta `inline-tools-2026-09-15`, poderá adicionar um servidor MCP no meio de uma conversa. Consulte [Adicionar um servidor MCP no meio da conversa](https://platform.claude.com/docs/pt-BR/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta).
## Múltiplos servidores MCP
Você pode se conectar a múltiplos servidores MCP incluindo múltiplas definições de servidor em `mcp_servers` e um MCPToolset correspondente para cada um no 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
}
}
]
}
```
Com muitas ferramentas disponíveis, o Claude seleciona com base nos nomes e descrições das ferramentas. Descrições de ferramentas claras e específicas melhoram a precisão da seleção. Para grandes conjuntos de ferramentas (dezenas de ferramentas em vários servidores), considere habilitar [`defer_loading`](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector#tool-configuration-options) com a [ferramenta de busca de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-search-tool) para que apenas as ferramentas relevantes sejam apresentadas por consulta.
## Autenticação
Para servidores MCP que exigem autenticação OAuth, você precisará obter um token de acesso. O beta do conector MCP suporta a passagem de um parâmetro `authorization_token` na definição do servidor MCP. Espera-se que os consumidores da API lidem com o fluxo OAuth e obtenham o token de acesso antes de fazer a chamada à API, além de atualizar o token conforme necessário.
### Obtendo um token de acesso para testes
O MCP inspector pode guiá-lo pelo processo de obtenção de um token de acesso para fins de teste.
1. Execute o inspector com o seguinte comando. Você precisa ter o Node.js instalado na sua máquina.
```bash
npx @modelcontextprotocol/inspector
```
2. Na barra lateral à esquerda, em **Transport type**, selecione **SSE** ou **Streamable HTTP**.
3. Insira a URL do servidor MCP.
4. Na área à direita, clique em **Open Auth Settings** após **Need to configure authentication?**.
5. Clique em **Quick OAuth Flow** e autorize na tela do OAuth.
6. Siga as etapas na seção **OAuth Flow Progress** do inspector e clique em **Continue** até chegar a **Authentication complete**.
7. Copie o valor de `access_token`.
8. Cole-o no campo `authorization_token` na configuração do seu servidor MCP.
### Usando o token de acesso
Depois de obter um token de acesso usando qualquer um dos fluxos OAuth anteriores, você pode usá-lo na configuração do seu servidor MCP:
```json
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}
```
Para explicações detalhadas sobre o fluxo OAuth, consulte a [seção Authorization](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) na especificação MCP.
## Helpers MCP do lado do cliente
Se você gerencia sua própria conexão de cliente MCP (por exemplo, com servidores stdio locais, prompts MCP ou recursos MCP), o SDK fornece funções auxiliares ("helpers") que convertem entre tipos MCP e tipos da Claude API. Isso elimina código de conversão manual ao usar um SDK MCP para a sua linguagem (por exemplo, o [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk)) junto com o SDK da Anthropic.
Use o [parâmetro de API `mcp_servers`](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api) quando você tiver servidores remotos acessíveis por URL e precisar apenas de suporte a ferramentas. Use os helpers do lado do cliente quando precisar de servidores locais, prompts, recursos ou mais controle sobre a conexão com o SDK base.
### Instalação
Instale o SDK da Anthropic e o SDK MCP:
Os helpers MCP estão incluídos no extra `mcp`, que requer Python 3.10 ou posterior:
```bash
pip install "anthropic[mcp]"
```
```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```
Os helpers ficam no pacote separado `Anthropic.Mcp`; o próprio cliente MCP vem do [pacote oficial ModelContextProtocol](https://www.nuget.org/packages/ModelContextProtocol):
```bash
dotnet add package Anthropic.Mcp
dotnet add package ModelContextProtocol
```
Os helpers ficam no subpacote `mcp` do SDK Go, que é construído sobre o [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk):
```bash
go get github.com/anthropics/anthropic-sdk-go/mcp
```
Os helpers ficam no artefato separado `anthropic-java-mcp`, que requer Java 17 ou posterior (o SDK base suporta Java 8). Adicione-o junto com a dependência 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
```
Os helpers usam o [MCP PHP SDK](https://packagist.org/packages/mcp/sdk) oficial:
```bash
composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" "mcp/sdk"
```
Os helpers usam a [gem `mcp`](https://rubygems.org/gems/mcp) oficial:
```bash
bundle add anthropic mcp
```
### Helpers disponíveis
Importe os helpers para a sua linguagem:
```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"
# Os helpers são expostos no módulo Anthropic::Mcp
```
| Helper | Descrição |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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)`) | Converte ferramentas MCP em ferramentas da Claude API para uso com `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)`) | Converte mensagens de prompt MCP para o formato de mensagem da Claude API |
| `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)`) | Converte um recurso MCP em um bloco de conteúdo da Claude API |
| `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)`) | Converte um recurso MCP em um objeto de arquivo para upload |
### Usar ferramentas MCP
Converta ferramentas MCP para uso com o [tool runner](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-runner) do SDK, que lida com a execução de ferramentas automaticamente:
```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:
# Conectar a um 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 as ferramentas e convertê-las para a API do 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();
// Conecte-se a um 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);
// Liste as ferramentas e converta-as para a API do Claude
const { tools } = await mcpClient.listTools();
// O tipo de retorno de callTool do SDK do MCP ainda inclui um formato de resultado legado que
// mcpTools não aceita; restrinja-o. Remova isso quando MCPClientLike for ampliado.
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();
// Conecta a um servidor MCP
await using var mcpClient = await McpClient.CreateAsync(
new StdioClientTransport(new StdioClientTransportOptions { Command = "mcp-server" })
);
// Lista as ferramentas e as converte para a API do 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()
// Conectar a um 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 as ferramentas e convertê-las para a API do 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();
// Conectar a um 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 ferramentas e convertê-las para a API do 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();
// O runner produz uma mensagem por turno do assistente; a última é a resposta 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();
// Conecta a um servidor MCP. O cliente MCP em PHP conecta via HTTP; aponte isto
// para o endpoint do seu servidor.
$mcp = Client::builder()->build();
$mcp->connect(new HttpTransport('http://localhost:8000/mcp'));
// Lista as ferramentas e as converte para a API do 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
# Conectar a um servidor MCP
transport = MCP::Client::Stdio.new(command: "mcp-server")
mcp_client = MCP::Client.new(transport: transport)
mcp_client.connect
# Listar as ferramentas e convertê-las para a API do 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 MCP
Converta mensagens de prompt MCP para o formato de mensagem da Claude API:
```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 MCP
Converta recursos MCP em blocos de conteúdo para incluir em mensagens, ou em objetos de arquivo para upload:
```python Python
from anthropic.lib.tools.mcp import (
mcp_resource_to_content,
mcp_resource_to_file,
)
# Como um bloco de conteúdo em uma mensagem
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 um upload de arquivo
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 um bloco de conteúdo em uma mensagem
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 um upload de arquivo
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 um bloco de conteúdo em uma mensagem
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 um upload de arquivo
var fileResource = await mcpClient.ReadResourceAsync("file:///path/to/data.json");
var (filename, data, mediaType) = BetaMcp.ResourceToFile(fileResource);
// Construa a parte do arquivo explicitamente para que o nome do arquivo e o tipo MIME do recurso
// sejam preservados no upload.
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 um bloco de conteúdo em uma mensagem
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 retorna a união de conteúdo de tool-result; o conteúdo
// da mensagem é um tipo de união separado, então reempacote as variantes compartilhadas
// (mcp.ToMessage faz o mesmo 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 um upload de arquivo
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 um bloco de conteúdo em uma mensagem
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 um upload de arquivo
McpSchema.ReadResourceResult fileResource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/data.json"));
McpResourceFile resourceFile = BetaMcp.mcpResourceFiles(fileResource).getFirst();
// Construa a parte do arquivo explicitamente para que o nome do arquivo e o tipo MIME do recurso
// sejam preservados no upload.
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 um bloco de conteúdo em uma mensagem
$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 um upload de arquivo
$fileResource = $mcp->readResource('file:///path/to/data.json');
$file = $anthropic->files->upload(file: BetaMcp::resourceToFile($fileResource));
echo $file->id, "\n";
```
```ruby Ruby
# Como um bloco de conteúdo em uma mensagem
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 um upload de arquivo
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
```
### Tratamento de erros
As funções de conversão falham com `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) se um valor MCP não for suportado pela Claude API (lançado como exceção ou, em Go, retornado como erro). Isso pode acontecer com tipos de conteúdo, tipos MIME ou links de recursos não suportados (resolva os links de recursos com seu cliente MCP antes de converter).
## Requisições em lote
Você pode incluir `mcp_servers` em requisições da [API Message Batches](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing). Chamadas de ferramentas MCP por meio da API Batches têm o mesmo preço que aquelas em requisições regulares da API Messages.
## Retenção de dados
O conector MCP não é coberto por acordos de ZDR. Os dados trocados com servidores MCP, incluindo definições de ferramentas e resultados de execução, são retidos de acordo com a política padrão de retenção de dados da Anthropic.
Para a elegibilidade de ZDR em todos os recursos, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).
## Guia de migração
Se você está usando o cabeçalho beta descontinuado `mcp-client-2025-04-04`, siga este guia para migrar para a nova versão.
### Principais mudanças
1. **Novo cabeçalho beta:** Mude de `mcp-client-2025-04-04` para `mcp-client-2025-11-20`
2. **Configuração de ferramentas movida:** A configuração de ferramentas agora fica no array `tools` como objetos MCPToolset, não na definição do servidor MCP
3. **Configuração mais flexível:** O novo padrão suporta listas de permissão, listas de bloqueio e configuração por ferramenta
### Etapas de migração
**Antes (descontinuado):**
```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"]
}
}
]
}
```
**Depois (atual):**
```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
}
}
}
]
}
```
### Padrões comuns de migração
| Padrão antigo | Novo padrão |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Sem `tool_configuration` (todas as ferramentas habilitadas) | MCPToolset sem `default_config` ou `configs` |
| `tool_configuration.enabled: false` | MCPToolset com `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset com `default_config.enabled: false` e ferramentas específicas habilitadas em `configs` |
## Versão descontinuada: mcp-client-2025-04-04
Esta versão está descontinuada. Migre para `mcp-client-2025-11-20` usando o [guia de migração](https://platform.claude.com/docs/pt-BR/agents-and-tools/mcp-connector#migration-guide) anterior.
A versão anterior do conector MCP incluía a configuração de ferramentas diretamente na definição do 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"]
}
}
]
}
```
### Descrições dos campos descontinuados
| Propriedade | Tipo | Descrição |
| ---------------------------------- | ------- | --------------------------------------------------------------------------------- |
| `tool_configuration` | object | **Descontinuado:** Use MCPToolset no array `tools` em vez disso |
| `tool_configuration.enabled` | boolean | **Descontinuado:** Use `default_config.enabled` no MCPToolset |
| `tool_configuration.allowed_tools` | array | **Descontinuado:** Use o padrão de lista de permissão com `configs` no MCPToolset |