Loading...
    • Guia do Desenvolvedor
    • Referência da API
    • MCP
    • Recursos
    • Notas de lançamento
    Search...
    ⌘K
    Primeiros passos
    Introdução ao ClaudeInício rápido
    Modelos e preços
    Visão geral dos modelosEscolhendo um modeloNovidades no Claude 4.6Guia de migraçãoDescontinuação de modelosPreços
    Construir com Claude
    Visão geral de recursosUsando a API MessagesTratando razões de paradaMelhores práticas de prompts
    Gerenciamento de contexto
    Janelas de contextoCompactaçãoEdição de contexto
    Capacidades
    Cache de promptsPensamento estendidoPensamento adaptativoEsforçoStreaming de mensagensProcessamento em loteCitaçõesSuporte multilíngueContagem de tokensEmbeddingsVisãoSuporte a PDFAPI de ArquivosResultados de pesquisaSaídas estruturadas
    Ferramentas
    Visão geralComo implementar o uso de ferramentasStreaming de ferramentas granularFerramenta BashFerramenta de execução de códigoChamada de ferramentas programáticaFerramenta de uso de computadorFerramenta de editor de textoFerramenta de busca na webFerramenta de pesquisa na webFerramenta de memóriaFerramenta de busca de ferramentas
    Habilidades de agente
    Visão geralInício rápidoMelhores práticasHabilidades para empresasUsando habilidades com a API
    Agent SDK
    Visão geralInício rápidoSDK TypeScriptTypeScript V2 (prévia)SDK PythonGuia de migração
    MCP na API
    Conector MCPServidores MCP remotos
    Claude em plataformas de terceiros
    Amazon BedrockMicrosoft FoundryVertex AI
    Engenharia de prompts
    Visão geralGerador de promptsUsar modelos de promptsMelhorador de promptsSeja claro e diretoUse exemplos (prompting multishotshot)Deixe Claude pensar (CoT)Use tags XMLDê um papel ao Claude (prompts do sistema)Encadear prompts complexosDicas de contexto longoDicas de pensamento estendido
    Testar e avaliar
    Definir critérios de sucessoDesenvolver casos de testeUsando a ferramenta de avaliaçãoReduzindo latência
    Fortalecer proteções
    Reduzir alucinaçõesAumentar consistência de saídaMitigar jailbreaksRecusas de streamingReduzir vazamento de promptManter Claude em personagem
    Administração e monitoramento
    Visão geral da API AdminResidência de dadosEspaços de trabalhoAPI de uso e custoAPI de análise de código ClaudeRetenção zero de dados
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    MCP na API

    Conector MCP

    Conecte-se a servidores MCP remotos diretamente da API de Mensagens sem um cliente MCP separado.

    O recurso de conector Model Context Protocol (MCP) do Claude permite que você se conecte a servidores MCP remotos diretamente da API de Mensagens sem um cliente MCP separado.

    Versão atual: Este recurso requer o cabeçalho beta: "anthropic-beta": "mcp-client-2025-11-20"

    A versão anterior (mcp-client-2025-04-04) está descontinuada. Consulte a documentação da versão descontinuada abaixo.

    Recursos principais

    • Integração direta de API: Conecte-se a servidores MCP sem implementar um cliente MCP
    • Suporte a chamadas de ferramentas: Acesse ferramentas MCP através da API de Mensagens
    • Configuração flexível de ferramentas: Ative todas as ferramentas, liste especificamente ferramentas ou bloqueie ferramentas indesejadas
    • Configuração por ferramenta: Configure ferramentas individuais com configurações personalizadas
    • Autenticação OAuth: Suporte para tokens Bearer OAuth para servidores autenticados
    • Múltiplos servidores: Conecte-se a vários servidores MCP em uma única solicitação

    Limitações

    • Do conjunto de recursos da especificação MCP, apenas chamadas de ferramentas são atualmente suportadas.
    • O servidor deve ser exposto publicamente através de HTTP (suporta transportes HTTP Streamable e SSE). Servidores STDIO locais não podem ser conectados diretamente.
    • O conector MCP não é atualmente suportado no Amazon Bedrock e Google Vertex.

    Usando o conector MCP na API de Mensagens

    O conector MCP usa dois componentes:

    1. Definição do Servidor MCP (array mcp_servers): Define detalhes de conexão do servidor (URL, autenticação)
    2. Conjunto de Ferramentas MCP (array tools): Configura quais ferramentas ativar e como configurá-las

    Exemplo básico

    Este exemplo ativa todas as ferramentas de um servidor MCP com configuração padrão:

    curl https://api.anthropic.com/v1/messages \
      -H "Content-Type: application/json" \
      -H "X-API-Key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "anthropic-beta: mcp-client-2025-11-20" \
      -d '{
        "model": "claude-opus-4-6",
        "max_tokens": 1000,
        "messages": [{"role": "user", "content": "What tools do you have available?"}],
        "mcp_servers": [
          {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN"
          }
        ],
        "tools": [
          {
            "type": "mcp_toolset",
            "mcp_server_name": "example-mcp"
          }
        ]
      }'

    Configuração do servidor MCP

    Cada servidor MCP no array mcp_servers define os detalhes de conexão:

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

    Descrições de campos

    PropriedadeTipoObrigatórioDescrição
    typestringSimAtualmente apenas "url" é suportado
    urlstringSimA URL do servidor MCP. Deve começar com https://
    namestringSimUm identificador único para este servidor MCP. Deve ser referenciado por exatamente um MCPToolset no array tools.
    authorization_tokenstringNãoToken de autorização OAuth se exigido pelo servidor MCP. Consulte a especificação MCP.

    Configuração do conjunto de ferramentas MCP

    O MCPToolset reside no array tools e configura quais ferramentas do servidor MCP estão ativadas e como devem ser configuradas.

    Estrutura básica

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

    Descrições de campos

    PropriedadeTipoObrigatórioDescrição
    typestringSimDeve ser "mcp_toolset"
    mcp_server_namestringSimDeve corresponder a um nome de servidor definido no array mcp_servers
    default_configobjectNãoConfiguração padrão aplicada a todas as ferramentas neste conjunto. Configurações de ferramentas individuais em configs substituirão esses padrões.
    configsobjectNãoSubstituições de configuração por ferramenta. As chaves são nomes de ferramentas, os valores são objetos de configuração.
    cache_controlobjectNãoConfiguração de ponto de interrupção de cache para este conjunto de ferramentas

    Opções de configuração de ferramentas

    Cada ferramenta (seja configurada em default_config ou em configs) suporta os seguintes campos:

    PropriedadeTipoPadrãoDescrição
    enabledbooleantrueSe esta ferramenta está ativada
    defer_loadingbooleanfalseSe verdadeiro, a descrição da ferramenta não é enviada ao modelo inicialmente. Usado com Ferramenta de Busca de Ferramentas.

    Mesclagem de configuração

    Os valores de configuração se mesclam com esta precedência (maior para menor):

    1. Configurações específicas de ferramentas em configs
    2. default_config no nível do conjunto
    3. Padrões do sistema

    Exemplo:

    {
      "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 de configuração comuns

    Ativar todas as ferramentas com configuração padrão

    O padrão mais simples - ativar todas as ferramentas de um servidor:

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

    Lista de permissões - Ativar apenas ferramentas específicas

    Defina enabled: false como padrão e, em seguida, ative explicitamente ferramentas específicas:

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

    Lista de bloqueio - Desativar ferramentas específicas

    Ative todas as ferramentas por padrão e, em seguida, desative explicitamente ferramentas indesejadas:

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

    Misto - Lista de permissões com configuração por ferramenta

    Combine lista de permissões com configuração personalizada para cada ferramenta:

    {
      "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á ativado com defer_loading: false
    • list_events está ativado com defer_loading: true (herdado de default_config)
    • Todas as outras ferramentas estão desativadas

    Regras de validação

    A API impõe estas regras de validação:

    • Servidor deve existir: O mcp_server_name em um MCPToolset deve corresponder a um servidor definido no array mcp_servers
    • Servidor deve ser usado: Cada servidor MCP definido em mcp_servers deve ser referenciado por exatamente um MCPToolset
    • Conjunto de ferramentas único por servidor: Cada servidor MCP pode ser referenciado por apenas um MCPToolset
    • Nomes de ferramentas desconhecidos: Se um nome de ferramenta em configs não existir no servidor MCP, um aviso de backend é registrado, mas nenhum erro é retornado (servidores MCP podem ter disponibilidade dinâmica de ferramentas)

    Tipos de conteúdo de resposta

    Quando Claude usa ferramentas MCP, a resposta incluirá dois novos tipos de bloco de conteúdo:

    Bloco de Uso de Ferramenta MCP

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

    Bloco de Resultado de Ferramenta MCP

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

    Múltiplos servidores MCP

    Você pode conectar-se a vários servidores MCP incluindo múltiplas definições de servidor em mcp_servers e um MCPToolset correspondente para cada um no array tools:

    {
      "model": "claude-opus-4-6",
      "max_tokens": 1000,
      "messages": [
        {
          "role": "user",
          "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
        }
      ],
      "mcp_servers": [
        {
          "type": "url",
          "url": "https://mcp.example1.com/sse",
          "name": "mcp-server-1",
          "authorization_token": "TOKEN1"
        },
        {
          "type": "url",
          "url": "https://mcp.example2.com/sse",
          "name": "mcp-server-2",
          "authorization_token": "TOKEN2"
        }
      ],
      "tools": [
        {
          "type": "mcp_toolset",
          "mcp_server_name": "mcp-server-1"
        },
        {
          "type": "mcp_toolset",
          "mcp_server_name": "mcp-server-2",
          "default_config": {
            "defer_loading": true
          }
        }
      ]
    }

    Autenticação

    Para servidores MCP que exigem autenticação OAuth, você precisará obter um token de acesso. O beta do conector MCP suporta passar um parâmetro authorization_token na definição do servidor MCP. Os consumidores de API devem lidar com o fluxo OAuth e obter o token de acesso antes de fazer a chamada de API, bem como atualizar o token conforme necessário.

    Obtendo um token de acesso para testes

    O inspetor MCP pode guiá-lo através do processo de obtenção de um token de acesso para fins de teste.

    1. Execute o inspetor com o seguinte comando. Você precisa ter Node.js instalado em sua máquina.

      npx @modelcontextprotocol/inspector
    2. Na barra lateral à esquerda, para "Tipo de transporte", selecione "SSE" ou "HTTP Streamable".

    3. Digite a URL do servidor MCP.

    4. Na área à direita, clique no botão "Abrir Configurações de Autenticação" após "Precisa configurar autenticação?".

    5. Clique em "Fluxo OAuth Rápido" e autorize na tela OAuth.

    6. Siga as etapas na seção "Progresso do Fluxo OAuth" do inspetor e clique em "Continuar" até atingir "Autenticação concluída".

    7. Copie o valor de access_token.

    8. Cole-o no campo authorization_token em sua configuração de servidor MCP.

    Usando o token de acesso

    Depois de obter um token de acesso usando qualquer um dos fluxos OAuth acima, você pode usá-lo em sua configuração de servidor MCP:

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

    Para explicações detalhadas do fluxo OAuth, consulte a seção de Autorização na especificação MCP.

    Auxiliares MCP do lado do cliente (TypeScript)

    Se você gerenciar sua própria conexão de cliente MCP (por exemplo, com servidores stdio locais, prompts MCP ou recursos MCP), o SDK TypeScript fornece funções auxiliares que convertem entre tipos MCP e tipos de API Claude. Isso elimina código de conversão manual ao usar o SDK MCP junto com o SDK Anthropic.

    Esses auxiliares estão atualmente disponíveis apenas no SDK TypeScript.

    Use o parâmetro de API mcp_servers quando você tiver servidores remotos acessíveis via URL e precisar apenas de suporte a ferramentas. Se você estiver usando o Agent SDK, as conexões MCP são gerenciadas automaticamente. Use os auxiliares 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 Anthropic e o SDK MCP:

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

    Auxiliares disponíveis

    Importe os auxiliares do namespace beta:

    import {
      mcpTools,
      mcpMessages,
      mcpResourceToContent,
      mcpResourceToFile,
    } from '@anthropic-ai/sdk/helpers/beta/mcp';
    AuxiliarDescrição
    mcpTools(tools, mcpClient)Converte ferramentas MCP para ferramentas de API Claude para uso com client.beta.messages.toolRunner()
    mcpMessages(messages)Converte mensagens de prompt MCP para formato de mensagem de API Claude
    mcpResourceToContent(resource)Converte um recurso MCP para um bloco de conteúdo de API Claude
    mcpResourceToFile(resource)Converte um recurso MCP para um objeto de arquivo para upload

    Usar ferramentas MCP

    Converta ferramentas MCP para uso com o executador de ferramentas do SDK, que manipula a execução de ferramentas automaticamente:

    import Anthropic from '@anthropic-ai/sdk';
    import { mcpTools } from '@anthropic-ai/sdk/helpers/beta/mcp';
    import { Client } from '@modelcontextprotocol/sdk/client/index.js';
    import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
    
    const anthropic = new Anthropic();
    
    // Connect to an MCP server
    const transport = new StdioClientTransport({ command: 'mcp-server', args: [] });
    const mcpClient = new Client({ name: 'my-client', version: '1.0.0' });
    await mcpClient.connect(transport);
    
    // List tools and convert them for the Claude API
    const { tools } = await mcpClient.listTools();
    const runner = await anthropic.beta.messages.toolRunner({
      model: 'claude-sonnet-4-5',
      max_tokens: 1024,
      messages: [{ role: 'user', content: 'What tools do you have available?' }],
      tools: mcpTools(tools, mcpClient),
    });

    Usar prompts MCP

    Converta mensagens de prompt MCP para formato de mensagem de API Claude:

    import { mcpMessages } from '@anthropic-ai/sdk/helpers/beta/mcp';
    
    const { messages } = await mcpClient.getPrompt({ name: 'my-prompt' });
    const response = await anthropic.beta.messages.create({
      model: 'claude-sonnet-4-5',
      max_tokens: 1024,
      messages: mcpMessages(messages),
    });

    Usar recursos MCP

    Converta recursos MCP em blocos de conteúdo para incluir em mensagens ou em objetos de arquivo para upload:

    import { mcpResourceToContent, mcpResourceToFile } from '@anthropic-ai/sdk/helpers/beta/mcp';
    
    // As a content block in a message
    const resource = await mcpClient.readResource({ uri: 'file:///path/to/doc.txt' });
    await anthropic.beta.messages.create({
      model: 'claude-sonnet-4-5',
      max_tokens: 1024,
      messages: [
        {
          role: 'user',
          content: [
            mcpResourceToContent(resource),
            { type: 'text', text: 'Summarize this document' },
          ],
        },
      ],
    });
    
    // As a file upload
    const fileResource = await mcpClient.readResource({ uri: 'file:///path/to/data.json' });
    await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

    Tratamento de erros

    As funções de conversão lançam UnsupportedMCPValueError se um valor MCP não for suportado pela API Claude. Isso pode acontecer com tipos de conteúdo não suportados, tipos MIME ou links de recursos não-HTTP.

    Guia de migração

    Se você estiver 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 reside 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 lista de permissões, lista de bloqueio e configuração por ferramenta

    Etapas de migração

    Antes (descontinuado):

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

    Depois (atual):

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

    Padrões de migração comuns

    Padrão antigoNovo padrão
    Sem tool_configuration (todas as ferramentas ativadas)MCPToolset sem default_config ou configs
    tool_configuration.enabled: falseMCPToolset com default_config.enabled: false
    tool_configuration.allowed_tools: [...]MCPToolset com default_config.enabled: false e ferramentas específicas ativadas em configs

    Versão descontinuada: mcp-client-2025-04-04

    Esta versão está descontinuada. Por favor, migre para mcp-client-2025-11-20 usando o guia de migração acima.

    A versão anterior do conector MCP incluía configuração de ferramentas diretamente na definição do servidor MCP:

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

    Descrições de campos descontinuados

    PropriedadeTipoDescrição
    tool_configurationobjectDescontinuado: Use MCPToolset no array tools em vez disso
    tool_configuration.enabledbooleanDescontinuado: Use default_config.enabled em MCPToolset
    tool_configuration.allowed_toolsarrayDescontinuado: Use padrão de lista de permissões com configs em MCPToolset

    Was this page helpful?

    • Recursos principais
    • Limitações
    • Usando o conector MCP na API de Mensagens
    • Exemplo básico
    • Configuração do servidor MCP
    • Descrições de campos
    • Configuração do conjunto de ferramentas MCP
    • Estrutura básica
    • Descrições de campos
    • Opções de configuração de ferramentas
    • Mesclagem de configuração
    • Padrões de configuração comuns
    • Ativar todas as ferramentas com configuração padrão
    • Lista de permissões - Ativar apenas ferramentas específicas
    • Lista de bloqueio - Desativar ferramentas específicas
    • Misto - Lista de permissões com configuração por ferramenta
    • Regras de validação
    • Tipos de conteúdo de resposta
    • Bloco de Uso de Ferramenta MCP
    • Bloco de Resultado de Ferramenta MCP
    • Múltiplos servidores MCP
    • Autenticação
    • Obtendo um token de acesso para testes
    • Usando o token de acesso
    • Auxiliares MCP do lado do cliente (TypeScript)
    • Instalação
    • Auxiliares disponíveis
    • Usar ferramentas MCP
    • Usar prompts MCP
    • Usar recursos MCP
    • Tratamento de erros
    • Guia de migração
    • Principais mudanças
    • Etapas de migração
    • Padrões de migração comuns
    • Versão descontinuada: mcp-client-2025-04-04
    • Descrições de campos descontinuados