Ferramentas Externas e SDKs Suportados
Nesta página
Três pontos de entrada para o mesmo mecanismo
A xAI expõe o MCP remoto através de três interfaces. Cada uma destina-se a um tipo diferente de programador: uma para novos projetos, outra para projetos migrados e a terceira para contextos de utilização específicos. O comportamento do MCP é exatamente o mesmo nos três casos; apenas a sintaxe de configuração e as ferramentas periféricas mudam. A sua escolha depende, portanto, da sua stack existente, e não das capacidades do protocolo.
O SDK nativo da xAI
Este é o método recomendado pela xAI. Fornece um auxiliar mcp() que condensa a configuração numa única chamada de função.
from xai_sdk import Client
from xai_sdk.tools import mcp
client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
model="grok-4.20-0309-reasoning",
tools=[
mcp(server_url="https://mcp.deepwiki.com/mcp")
],
include=["verbose_streaming"],
)
O auxiliar mcp() aceita todos os parâmetros de configuração do MCP — URL, etiqueta, descrição, ferramentas permitidas, autenticação — e trata da sua formatação correta para a API. Esta é a sintaxe mais concisa e, crucialmente, aquela em que é menos provável cometer erros, uma vez que os nomes das chaves e a aninhamento são geridos automaticamente. Escolha este caminho para um novo projeto sem restrições de compatibilidade, para qualquer prototipagem rápida e sempre que utilizar funcionalidades específicas da xAI, como o streaming detalhado visível acima.
A API Responses, compatível com OpenAI
Esta interface aceita exatamente o formato da API OpenAI. Existe por uma razão específica: para que uma equipa que já tenha escrito a sua aplicação neste formato não tenha de reescrever tudo para experimentar o Grok. A alteração limita-se à chave da API e ao URL base.
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("XAI_API_KEY"),
base_url="https://api.x.ai/v1",
)
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input=[{"role": "user", "content": "Explain the React project"}],
tools=[{
"type": "mcp",
"server_url": "https://mcp.deepwiki.com/mcp",
"server_label": "deepwiki",
}],
)
Aqui, o servidor MCP é declarado como um elemento do array tools, com o tipo "mcp" e os parâmetros como pares chave-valor no mesmo objeto. Sem auxiliar: escreve o dicionário manualmente, o que deixa mais margem para erros de digitação nos nomes das chaves.
Esta compatibilidade tem um custo, e deve conhecê-lo antes de construir sobre ela. Dois parâmetros disponíveis no SDK nativo não estão disponíveis aqui: require_approval, que permite exigir validação humana antes de executar uma ferramenta MCP, e connector_id, que gere conectores OpenAI. Se o seu agente lida com operações sensíveis e contava com validação manual, esta limitação é um bloqueio e deve levá-lo de volta ao SDK nativo da xAI. A API Responses continua a ser a escolha certa para uma migração a partir da OpenAI sem reescrita, para um projeto multi-fornecedor onde alterna entre o Grok e outros modelos, e para uma equipa já familiarizada com este formato.
A API Voice Agent
A terceira interface foi concebida para agentes de voz. O cenário típico é um assistente telefónico que, no meio de uma conversa, precisa de consultar uma base de conhecimentos, verificar o estado de uma encomenda ou consultar um sistema externo — sem que o interlocutor experiencie um silêncio inexplicável.
A configuração do MCP segue o mesmo formato dos outros SDKs, com os mesmos parâmetros server_url, server_label e outros. A diferença reside no que acontece após a chamada da ferramenta: o resultado é integrado no fluxo de síntese de voz em vez de ser apresentado como texto. Isto molda a forma como escreve as descrições das suas ferramentas e enquadra as suas respostas, uma vez que o utilizador nunca verá uma tabela ou uma lista — apenas as ouvirá.
O que não muda entre interfaces
Seja qual for o SDK, a sequência é a mesma. O Grok descobre as ferramentas expostas pelo servidor MCP, seleciona a que corresponde ao pedido, formula a chamada com os parâmetros corretos e, em seguida, integra o resultado na sua resposta. Nenhuma das três interfaces torna o modelo mais ou menos competente na escolha de uma ferramenta.
As diferenças residem, portanto, noutros aspetos: concisão da sintaxe, funcionalidades periféricas disponíveis — streaming detalhado no SDK da xAI, compatibilidade de formato na API Responses, síntese de voz na Voice Agent — e os dois parâmetros em falta no formato OpenAI. Decida com base nestes critérios e não errará.
Pontos-chave
- O SDK nativo da xAI com
mcp()é o método mais simples e completo - A API Responses (formato OpenAI) facilita a migração, mas não suporta
require_approvalnemconnector_id - A API Voice Agent liga agentes de voz a ferramentas MCP
- O comportamento do MCP é idêntico nos três casos; apenas a sintaxe muda
- Escolha com base na sua stack existente e nas suas necessidades específicas