Saltar para o conteúdo principal
Um servidor MCP remoto é apenas um endpoint HTTP no qual seus agentes chamam ferramentas — e a maioria deles fica atrás de um token, um cliente OAuth ou auth básica. Quando você registra esse servidor atrás do gateway MCP do Firewall, você entrega a credencial ao OrcaRouter uma vez, escolhe como ele se autentica, e o gateway a injeta no momento do dispatch. O segredo é criptografado em repouso e nunca viaja até o modelo ou o código do seu agente. Esta página cobre o lado da autenticação ao registrar um servidor: os quatro formatos de auth_mode e o que acontece com sua credencial. Para tudo o que o gateway faz a cada tools/call depois que a conexão está de pé — política por chamada, namespacing, proteção contra SSRF — veja a referência do gateway MCP.

​
1. Por que autenticar no gateway

Sem um gateway, cada agente que fala com um servidor MCP carrega sua própria cópia do token desse servidor, espalhada por configs e prompts. Roteie o servidor através do OrcaRouter e a credencial vive em exatamente um lugar:
  • Um segredo armazenado por servidor. Você registra a credencial uma vez, no registro do workspace. Os agentes se conectam ao gateway com uma chave do OrcaRouter — eles nunca veem o token do servidor upstream.
  • Criptografada em repouso, mascarada na leitura. A credencial é criptografada quando é armazenada. Toda vez que você lê o servidor de volta através do console ou SDK, o segredo volta mascarado — não há API que o retorne em texto claro.
  • Injetada no dispatch. O gateway descriptografa a credencial apenas no momento em que encaminha um tools/call ao servidor real, e então a anexa a essa requisição outbound. Ela nunca é ecoada ao modelo ou ao cliente.
Uma credencial que você não pode ler de volta é um recurso, não uma lacuna. Como as leituras são sempre mascaradas, uma sessão de console ou um token de SDK vazado não pode exfiltrar os segredos do seu servidor MCP — só pode reapontá-los ou girá-los.

​
2. Escolha um auth_mode

Cada registro de servidor carrega um auth_mode. É um conjunto fechado de quatro valores, e ele decide o formato da credencial que você fornece em auth_json:
O servidor é aberto (ou confia no gateway por rede). Deixe auth_json vazio. Este é o padrão quando você não define auth_mode.
O caso mais comum para servidores MCP hospedados. Forneça um token; o gateway o envia como uma credencial bearer em cada chamada.
{ "token": "ghp_…" }
Para servidores protegidos por OAuth. Forneça um access_token que você já cunhou; o gateway o envia como uma credencial bearer, exatamente como bearer. A troca automática de client-credentials (trocar um client_id/client_secret por um token novo) ainda não está disponível — um registro oauth sem um access_token é rejeitado.
{ "access_token": "…" }
HTTP basic auth.
{ "username": "…", "password": "…" }
auth_json é obrigatório sempre que auth_mode for qualquer coisa diferente de none. Registrar um servidor bearer/oauth/basic com uma credencial vazia é rejeitado — o gateway não persistirá uma conexão meio-configurada.

​
3. Registrar um servidor MCP seguro — um exemplo

O registro de servidor MCP é uma ação de console: roda sob seu session / access token contra /api/workspace/firewall/mcp_servers, e escrever um servidor exige o papel de Developer+. (Isso é diferente da chave de relay sk-orca-… que você usa para chamadas de modelo /v1/* — essa chave nunca gerencia config de workspace.) Registre um servidor com auth bearer a partir do console do firewall, ou com seu session token diretamente: 
curl https://api.orcarouter.ai/api/workspace/firewall/mcp_servers \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "endpoint": "https://api.githubcopilot.com/mcp",
    "auth_mode": "bearer",
    "auth_json": "{\"token\":\"ghp_x\"}",
    "enabled": true
  }'
O name é único por workspace (um duplicado retorna HTTP 409), e não pode conter um . — esse caractere faz namespace das ferramentas como <server>.<tool>. Na entrada, o OrcaRouter criptografa auth_json e armazena apenas o ciphertext. Quando você lê o servidor de volta, obtém a forma mascarada.
Ecoe o valor mascarado de volta direto em uma atualização para manter o segredo armazenado inalterado — envie um auth_json real apenas quando você realmente quiser girá-lo. Veja rotação de credenciais para o fluxo de rotação.

​
4. Prove que a conexão funciona

A autenticação não está concluída até que o gateway possa de fato alcançar o servidor com a credencial que você armazenou. Faça probe dele: 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your-session-token>"
O gateway se conecta ao endpoint usando a credencial descriptografada, lista as ferramentas do servidor e registra um status de alcançabilidade:
statusSignificado
okAlcançado e autenticado; ferramentas descobertas.
degradedAlcançável mas não totalmente saudável.
downNão conseguiu conectar ou autenticar.
Um resultado down logo após o registro quase sempre significa uma credencial ruim ou o auth_mode errado — corrija auth_json e faça probe de novo. Fazer probe é uma ação de Developer+; o servidor in-process empacotado não tem endpoint e não é probeável.
Um servidor desabilitado é o interruptor de desligar limpo: suas ferramentas desaparecem do gateway e sua credencial nunca é descriptografada. Desabilite um servidor enquanto você resolve sua auth, depois reabilite assim que um probe voltar ok.

​
5. Lendo servidores a partir de um agente

Seus agentes não leem credenciais. Quando um proxy de SDK precisa do registro de runtime, ele chama GET /api/v1/firewall/mcp_servers com uma chave com escopo de firewall-gateway — uma chave dedicada, não sua chave de relay e não sua sessão. Esse path serve apenas servidores habilitados, e o gateway ainda detém a injeção de credencial de ponta a ponta. Conectar um agente ao endpoint MCP unificado é coberto na referência do gateway.

​
6. Para onde ir a seguir

Conectar seu primeiro servidor

O passo a passo completo de registro, de workspace vazio a uma ferramenta ativa.

Girar credenciais

Troque um segredo vazado ou expirando sem derrubar a conexão.

Lista de permissão de ferramentas MCP

Decida quais ferramentas de um servidor seus agentes podem de fato chamar.

Limitar egress

Restrinja onde as ferramentas de um servidor podem alcançar na rede.
Para os conceitos por trás disso — como o gateway fica no caminho da requisição e por que as credenciais nunca tocam o modelo — veja Como o OrcaRouter inspeciona e Segurança de agentes de IA. Para as ameaças que isso fecha, veja Envenenamento de ferramentas MCP e exfiltração de dados.