server_url e server_label
Nesta página
Atualizado em 3 de novembro de 2026 com base na página Remote MCP Tools da xAI: o
server_labeladiciona um prefixo às chamadas de ferramentas, mas a documentação não especifica o formato exato desse prefixo; a notaçãolabel__toolutilizada neste curso é uma convenção de leitura—verifique o formato real nas respostas da sua API. Fonte: Remote MCP Tools.
Os dois parâmetros indispensáveis
Qualquer ligação entre o Grok e um servidor MCP remoto depende de dois parâmetros: server_url e server_label. São inegociáveis—sem eles, a API rejeita o pedido antes de tentar qualquer coisa. Todos os outros parâmetros que encontrará mais tarde refinam esta base; nunca a substituem.
server_url: O endereço exato do endpoint
O parâmetro server_url contém o URL completo do servidor MCP ao qual o Grok se deve ligar, e este URL segue regras estritas.
A primeira é o HTTPS. O URL deve começar por https://, e a xAI rejeita qualquer ligação HTTP não encriptada. A razão é simples: as trocas entre o Grok e o servidor MCP transportam os pedidos dos seus utilizadores, os resultados das ferramentas e, por vezes, o próprio token de autenticação. Deixar isto circular em texto simples seria indefensável.
# Correto
mcp(server_url="https://mcp.deepwiki.com/mcp")
# Rejeitado pela API
mcp(server_url="http://mcp.deepwiki.com/mcp")
A segunda regra diz respeito à precisão do caminho. O URL deve apontar para o endpoint MCP, não para a raiz do domínio. Quase todos os servidores expõem o seu endpoint num caminho dedicado, e a convenção varia de um para outro. Eis três formas válidas que encontrará:
https://mcp.deepwiki.com/mcp
https://api.example.com/mcp
https://tools.monentreprise.com/v1/mcp
A terceira regra decorre das duas primeiras: localhost e endereços IP privados estão excluídos. O servidor deve ser acessível a partir da infraestrutura da xAI, num domínio público, com um certificado SSL válido. Isto levanta uma questão concreta durante o desenvolvimento, já que o servidor MCP que está a escrever corre na sua máquina. A solução habitual é utilizar um túnel—ngrok ou Cloudflare Tunnel, por exemplo—que expõe a sua instância local atrás de um URL HTTPS público durante a duração dos seus testes.
server_label: A identidade do servidor na conversa
O server_label é um identificador curto que o Grok utiliza para prefixar as chamadas de ferramentas provenientes deste servidor. O seu papel é duplo: tornar os registos legíveis e remover qualquer ambiguidade quando coexistem vários servidores.
A documentação da xAI afirma que o rótulo prefixa as chamadas de ferramentas deste servidor, sem especificar o formato exato do prefixo. Neste curso, denotamos uma ferramenta search_docs do servidor deepwiki como deepwiki__search_docs, para legibilidade: verifique o formato real nas respostas da API antes de construir lógica sobre ele.
mcp(
server_url="https://mcp.deepwiki.com/mcp",
server_label="deepwiki"
)
# As chamadas de ferramentas deste servidor terão o prefixo "deepwiki"
Três critérios orientam a escolha de um bom rótulo. Deve ser curto, uma vez que se soma ao nome de cada chamada e um rótulo verboso incha desnecessariamente os seus registos. Deve ser descritivo, para que a origem de uma chamada seja legível à primeira vista sem consultar a configuração. Deve ser único na sua configuração, caso contrário não conseguirá distinguir entre dois servidores. Os exemplos abaixo cumprem estes três requisitos:
server_label="deepwiki" # Documentação do GitHub
server_label="crm" # Sistema de gestão de clientes
server_label="jira" # Rastreio de tickets
server_label="search" # Motor de busca interno
Isto torna-se muito mais tangível assim que liga vários servidores à mesma sessão. Suponha que a sua documentação interna e o DeepWiki expõem ambos uma ferramenta chamada search. Sem rótulos distintos, os nomes das ferramentas colidem e o Grok não tem forma de saber qual delas visar. Com rótulos, as duas ferramentas recebem prefixos diferentes—aqui notadas como deepwiki__search e internal-docs__search—e a confusão desaparece. Voltará a este ponto na lição dedicada a múltiplos servidores.
Configuração mínima em ambos os SDKs
Juntos, estes dois parâmetros são suficientes para fazer funcionar um servidor MCP público. Com o SDK nativo da xAI:
from xai_sdk.tools import mcp
tools = [
mcp(
server_url="https://mcp.deepwiki.com/mcp",
server_label="deepwiki"
)
]
E o equivalente exato com a API de Responses no formato OpenAI:
tools = [{
"type": "mcp",
"server_url": "https://mcp.deepwiki.com/mcp",
"server_label": "deepwiki",
}]
Pontos-chave
server_urleserver_labelsão os únicos dois parâmetros obrigatórios- O URL deve ser HTTPS com um certificado SSL válido, sem localhost
- O rótulo prefixa todas as chamadas de ferramentas deste servidor (o formato exato não está documentado; este curso anota-o como
label__tool) - Escolha rótulos curtos, descritivos e únicos por servidor
- O rótulo é essencial para múltiplos servidores, a fim de evitar conflitos de nomes