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

Configuração Completa do Servidor MCP

Aula 7 de 12 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Juntar Todas as Peças
  2. O Caso Mais Simples
  3. Um Servidor Interno de Apenas Leitura
  4. Uma Configuração Abrangente
  5. Verificar Antes de Implementar
  6. Pontos-chave

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âmetroObrigatórioFunção
server_urlSimURL HTTPS do servidor MCP
server_labelSimPrefixo da chamada da ferramenta
server_descriptionNãoOrienta o Grok na seleção do servidor
allowed_tool_namesNãoRestringe as ferramentas acessíveis
authorizationNãoToken de autenticação
headersNãoCabeç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_url e server_label
  • Adicione server_description para orientar o Grok, especialmente em configurações com vários servidores
  • Restrinja com allowed_tool_names por segurança e desempenho
  • Utilize authorization e headers para autenticação
  • Ambos os SDK (xAI nativo e OpenAI Responses) aceitam os mesmos parâmetros com sintaxes diferentes