Autenticação e cabeçalhos
Nesta página
Prove quem está a chamar
O DeepWiki e outros servidores MCP públicos aceitam qualquer chamador, o que é coerente com a sua finalidade. Assim que expõe as suas próprias ferramentas, a situação muda: sem autenticação, qualquer pessoa que adivinhe o URL pode consultar o seu CRM ou acionar os seus processos. A xAI fornece dois parâmetros para resolver isto: authorization para o token de acesso e headers ou extra_headers para todo o resto.
O parâmetro authorization
Envia um token de autenticação para o servidor MCP. Especificamente, a cadeia de caracteres que fornece é colocada tal qual no cabeçalho HTTP Authorization de cada pedido enviado para esse servidor.
mcp(
server_url="https://api.example.com/mcp",
server_label="internal",
authorization="Bearer sk-your-token-here"
)
O formato esperado depende inteiramente do servidor de destino, pois authorization aceita qualquer cadeia de caracteres: é o servidor MCP que a valida, não a xAI. Três formas cobrem quase todos os casos que encontrará.
- Token Bearer:
"Bearer sk-xxxx"— o mais comum, utilizado pela maioria das APIs REST - Chave de API:
"ApiKey your-key"— alguns serviços utilizam um prefixo personalizado - Auth básica:
"Basic base64(user:password)"— autenticação básica codificada em base64
Como este token acompanha todos os pedidos, o seu manuseamento exige cuidado. Nunca o codifique diretamente no seu código-fonte: um segredo escrito num ficheiro versionado acaba inevitavelmente num repositório, num registo ou numa captura de ecrã. Utilize sempre uma variável de ambiente. Se o servidor o permitir, prefira um token com âmbito restrito que abra apenas as ferramentas de que realmente necessita — esta é a contraparte do lado do servidor para a restrição allowed_tool_names. E planeie uma rotação regular, especialmente em produção, onde um token eterno é um token que acabará por ser comprometido.
import os
mcp(
server_url="https://api.example.com/mcp",
server_label="internal",
authorization=f"Bearer {os.getenv('MCP_SERVER_TOKEN')}"
)
headers e extra_headers
O token responde à pergunta “quem é você?”. Muitos servidores necessitam de respostas adicionais: para qual organização, em qual ambiente, com qual versão da API. Esta informação passa através do parâmetro headers, ou extra_headers, dependendo do SDK.
mcp(
server_url="https://api.example.com/mcp",
server_label="internal",
authorization="Bearer sk-token",
headers={
"X-Organization-Id": "org-123",
"X-Project-Id": "proj-456"
}
)
O caso mais comum são as plataformas multi-inquilino, onde o mesmo endpoint serve vários clientes e depende de um cabeçalho para encaminhar o pedido para os dados corretos. Segue-se o versionamento da API, com um cabeçalho como "X-API-Version": "2024-01" que fixa uma versão específica e o protege de alterações no servidor. Alguns sistemas também esperam metadados de rastreio — ID de sessão, ID de agente — para traçar a origem das chamadas, ou cabeçalhos de limitação de taxa que determinam o plano de faturação aplicado.
O nome do parâmetro varia consoante a interface que utiliza. O SDK nativo da xAI usa headers na maioria dos casos; a API de Respostas no formato OpenAI pode exigir extra_headers, para evitar qualquer colisão com cabeçalhos que este SDK gere automaticamente para si próprio. O comportamento, no entanto, é exatamente o mesmo: os cabeçalhos são adicionados a cada pedido ao servidor MCP. Se os seus pedidos saírem sem os seus cabeçalhos, verifique primeiro este nome de parâmetro antes de procurar noutro lugar.
Uma configuração de produção completa
Eis como estes parâmetros se articulam com os das lições anteriores, num caso realista de servidor interno.
from xai_sdk.tools import mcp
import os
tools = [
mcp(
server_url="https://api.monentreprise.com/mcp",
server_label="internal",
server_description="Internal tools: CRM, documentation, tickets",
authorization=f"Bearer {os.getenv('INTERNAL_MCP_TOKEN')}",
headers={
"X-Organization-Id": os.getenv("ORG_ID"),
"X-Environment": "production"
},
allowed_tool_names=["search_docs", "get_ticket", "search_contacts"]
)
]
Esta configuração liga-se ao servidor MCP interno via HTTPS, autentica-se com um token Bearer armazenado numa variável de ambiente, envia o ID da organização num cabeçalho e restringe o acesso a três operações de leitura. Note que cada linha bloqueia um aspeto diferente: a encriptação protege o transporte, o token prova a identidade, o cabeçalho define o âmbito dos dados e a lista de permissões limita os danos potenciais. Nenhuma destas camadas substitui as outras.
Pontos-chave
authorizationenvia o token de acesso para o servidor MCP através do cabeçalho HTTP Authorization- Guarde sempre os seus tokens em variáveis de ambiente, nunca codificados diretamente no código
headers/extra_headersadicionam cabeçalhos HTTP extra a cada pedido- Os cabeçalhos servem para identificação multi-inquilino, versionamento de API e rastreio
- Combine autenticação e restrição de ferramentas para máxima segurança