Configuração Completa do Servidor MCP
Nesta página
Juntar Todas as Peças
Já encontrou cada parâmetro isoladamente. Esta lição reúne-os em configurações completas, exatamente como as escreverá na prática, mostrando sempre o equivalente nos dois SDK principais. O objetivo não é introduzir novos conceitos, mas fornecer padrões que possa adaptar diretamente.
Aqui tem uma visão geral dos seis parâmetros, com o seu estado obrigatório ou opcional.
| Parâmetro | Obrigatório | Função |
|---|---|---|
server_url | Sim | URL HTTPS do servidor MCP |
server_label | Sim | Prefixo da chamada da ferramenta |
server_description | Não | Orienta o Grok na seleção do servidor |
allowed_tool_names | Não | Restringe as ferramentas acessíveis |
authorization | Não | Token de autenticação |
headers | Não | Cabeçalhos HTTP adicionais |
O Caso Mais Simples
Dois parâmetros são suficientes quando o servidor é público e não requer autenticação.
# xAI SDK
tools = [mcp(server_url="https://mcp.deepwiki.com/mcp", server_label="deepwiki")]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
"server_url": "https://mcp.deepwiki.com/mcp",
"server_label": "deepwiki"
}]
É exatamente isto que escreverá para o DeepWiki. O Grok fica então com acesso a todas as ferramentas do servidor, o que permanece aceitável aqui, uma vez que se trata de um serviço público de apenas leitura. Assim que o servidor pertencer à sua organização, esta configuração torna-se insuficiente.
Um Servidor Interno de Apenas Leitura
Vamos subir um degrau: um CRM empresarial que o agente deve poder consultar, mas nunca modificar. São adicionados três parâmetros, cada um por uma razão distinta — a descrição orienta o modelo, o token prova a identidade e a lista de permissões proíbe escritas.
# xAI SDK
tools = [
mcp(
server_url="https://api.monentreprise.com/mcp",
server_label="crm",
server_description="Internal CRM. Contact and company lookup only.",
authorization=f"Bearer {os.getenv('CRM_TOKEN')}",
allowed_tool_names=["search_contacts", "get_contact", "list_companies"]
)
]
# Responses API (OpenAI)
tools = [{
"type": "mcp",
"server_url": "https://api.monentreprise.com/mcp",
"server_label": "crm",
"server_description": "Internal CRM. Contact and company lookup only.",
"authorization": f"Bearer {os.getenv('CRM_TOKEN')}",
"allowed_tool_names": ["search_contacts", "get_contact", "list_companies"]
}]
Compare os dois blocos: o conteúdo é idêntico; apenas o wrapper muda. A função auxiliar mcp() aceita argumentos nomeados; o formato da OpenAI espera um dicionário com uma chave "type" adicional. Esta é a única diferença a lembrar ao traduzir uma configuração de um SDK para o outro.
Uma Configuração Abrangente
Passo final, com todos os seis parâmetros combinados numa chamada real ao SDK da xAI.
import os
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://tools.monentreprise.com/v1/mcp",
server_label="outils-internes",
server_description="Internal tools platform: document management, support tickets, knowledge base. Read-only access.",
authorization=f"Bearer {os.getenv('TOOLS_MCP_TOKEN')}",
headers={
"X-Organization-Id": os.getenv("ORG_ID"),
"X-Environment": "production",
"X-Request-Source": "grok-agent"
},
allowed_tool_names=[
"search_documents",
"get_document",
"search_tickets",
"get_ticket",
"search_knowledge_base"
]
)
],
include=["verbose_streaming"],
)
Repare na consistência interna deste exemplo. A descrição anuncia acesso de apenas leitura e as cinco ferramentas permitidas são todas operações de consulta — não há contradição entre o que o modelo acredita poder fazer e o que a configuração permite. O cabeçalho X-Environment definido como production impede que um agente de teste escreva em dados reais, e o X-Request-Source tornará os registos do seu servidor acionáveis caso precise de rastrear a origem de um pedido inesperado.
Verificar Antes de Implementar
Seis pontos merecem uma revisão antes de qualquer implementação em produção, e cada um corresponde a uma armadilha encontrada anteriormente neste curso. O URL deve ser HTTPS com um certificado válido, caso contrário nada funcionará. O rótulo deve permanecer curto, descritivo e único dentro da configuração. A descrição deve corresponder às ferramentas realmente expostas, caso contrário o modelo tentará chamadas destinedas a falhar. As ferramentas permitidas devem ser reduzidas ao estrito mínimo. O token deve vir de uma variável de ambiente, não do código fonte. E os cabeçalhos adicionais devem ser exatamente o que o seu servidor espera, com a capitalização correta — um erro de capitalização em X-Organization-Id produz uma falha silenciosa particularmente dolorosa de diagnosticar.
Pontos-chave
- A configuração mínima requer apenas
server_urleserver_label - Adicione
server_descriptionpara orientar o Grok, especialmente em configurações com vários servidores - Restrinja com
allowed_tool_namespor segurança e desempenho - Utilize
authorizationeheaderspara autenticação - Ambos os SDK (xAI nativo e OpenAI Responses) aceitam os mesmos parâmetros com sintaxes diferentes