Ir para o conteúdo principal
Português— Escolher um idioma
Menu

server_url e server_label

Aula 4 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Os dois parâmetros indispensáveis
  2. server_url: O endereço exato do endpoint
  3. server_label: A identidade do servidor na conversa
  4. Configuração mínima em ambos os SDKs
  5. Pontos-chave

Atualizado em 3 de novembro de 2026 com base na página Remote MCP Tools da xAI: o server_label adiciona um prefixo às chamadas de ferramentas, mas a documentação não especifica o formato exato desse prefixo; a notação label__tool utilizada 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
Onde o servidor está localizado
server_label
Como identificar o servidor

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_url e server_label sã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