Saltar para o conteúdo principal
Você quer que seus agentes usem um servidor Model Context Protocol (MCP) — seu próprio servidor remoto, ou o empacotado — mas quer que cada chamada de ferramenta que ele expõe rode atrás de um único ponto de estrangulamento auditado. O primeiro passo é registrar o servidor no seu workspace: um nome, um endpoint, um modo de auth e suas credenciais. Uma vez registrado, o gateway MCP anuncia suas ferramentas sob uma conexão e avalia cada tools/call através da sua política de firewall antes de chegar ao servidor real. Esta página cobre essa única tarefa — conectar e configurar um registro de servidor. Para o comportamento de runtime do gateway e os vereditos por chamada, veja a referência MCP; para o panorama maior, comece na Visão geral de segurança MCP.
O registro é uma ação de console (as rotas /api/workspace/firewall/* autenticam com seu session / access token, não com uma chave de relay sk-orca-…). As escritas exigem o papel de Developer+; qualquer membro pode listar servidores.

​
1. Como conectar um servidor MCP

Abra Firewall → MCP Servers no console e adicione um servidor, ou chame a API de workspace diretamente. Um registro carrega quatro coisas que importam:

name

Único por workspace. Torna-se o prefixo de namespace <server>.<tool>, então um nome duplicado no mesmo workspace é rejeitado com HTTP 409.

endpoint

A URL do seu servidor MCP remoto. Deixe vazio para registrar o servidor in-process empacotado de modo que ele seja visível e governável.

auth_mode

Como o gateway se autentica no seu servidor: none, bearer, oauth ou basic.

credenciais

O segredo específico do modo. Armazenado criptografado em repouso e mascarado na leitura — ele nunca chega ao modelo ou ao cliente.
Um servidor começa enabled e é removido inteiramente do gateway no momento em que você o desabilita — esse é o interruptor de desligar, e as credenciais de um servidor desabilitado nunca são descriptografadas.

​
2. Um exemplo concreto

Registre um servidor MCP do GitHub remoto com um bearer token. Esta é uma chamada REST equivalente ao console; os nomes de campo são exatamente o que o formulário escreve. 
curl https://api.orcarouter.ai/api/workspace/firewall/mcp_servers \
  -H "Authorization: Bearer <your-session-or-access-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 formato da credencial depende do auth_mode:
{"token":"…"} — enviado como um bearer token para o seu servidor.
{"access_token":"…"} — um access token estático que o gateway envia como um header bearer. A troca automática de client-credentials ainda não é suportada; sem um access_token armazenado, um probe em modo oauth falha em vez de conectar sem autenticação.
{"username":"…","password":"…"}.
Uma string vazia. Nenhuma credencial é anexada.
Na leitura, tanto a credencial quanto o endpoint são mascarados — a API retorna placeholders sentinela, não os valores brutos. Quando você atualiza um servidor, ecoe esses placeholders de volta inalterados para manter os valores armazenados; envie um auth_json novo apenas quando estiver de fato girando o segredo. Veja rotação de credenciais.

​
3. Faça probe de sua saúde

Antes de poder escrever regras de firewall contra as ferramentas de um servidor, você precisa saber se elas são alcançáveis e como se chamam. Faça probe do servidor — o gateway roda um handshake MCP initialize + tools/list usando as credenciais descriptografadas, registra a alcançabilidade e retorna as ferramentas anunciadas: 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your-session-or-access-token>"

{
  "status": "ok",
  "last_checked_at": 1700000000,
  "tools": [
    { "name": "create_issue", "description": "…", "input_schema": {} }
  ]
}
O status cai no registro do servidor e dirige o indicador de saúde:
statusSignificado
okAlcançável; as ferramentas são servidas pelo gateway.
degradedAlcançável, mas o handshake foi parcial.
downInalcançável no último probe; o servidor é pulado.
Um servidor down é deixado de fora quando o gateway monta seu conjunto de ferramentas, de modo que uma queda transitória degrada graciosamente em vez de quebrar o dispatch. Um probe retorna seu resultado independentemente do desfecho — um probe que falha volta como 200 com status: down e uma razão higienizada, não um erro de transporte.
O servidor in-process empacotado (endpoint vazio) despacha localmente e não é probeável — fazer probe dele é rejeitado com um erro explicando que o registro não tem endpoint. Você só faz probe de servidores BYO que têm uma URL.
Cada mudança de registro invalida o cache de ferramentas por workspace do gateway imediatamente, de modo que um servidor recém-conectado, desabilitado ou re-probeado entra em vigor na próxima conexão em vez de após uma janela de cache.

​
4. Depois de conectado

Uma vez que um servidor esteja registrado e fazendo probe ok, suas ferramentas são governadas:
  • Cada chamada é avaliada. Cada tools/call roda através da sua política de firewall na superfície mcp antes de chegar ao seu servidor. Escope regras por tool_name_glob: github.* agora que você conhece os nomes das ferramentas.
  • Restrinja a superfície. Default para negar ferramentas que você não permitiu explicitamente — veja lista de permissão de ferramentas MCP.
  • Governe onde ela alcança. Crie uma regra de egress para que uma ferramenta não possa buscar hosts arbitrários.
  • Observe mudanças. Um servidor em que você confiou pode mudar suas definições de ferramenta depois do fato; a defesa contra rug-pull sinaliza esse drift.

​
5. API reference

Todas as rotas de console têm escopo de workspace e autenticam com seu session / access token. Leituras de lista estão abertas a qualquer Member (segredos mascarados); cada escrita exige Developer+.
Método & pathPapelPropósito
GET /api/workspace/firewall/mcp_serversMemberLista servidores (segredos + endpoint mascarados).
GET /api/workspace/firewall/mcp_servers/:idMemberServidor único, mascarado.
POST /api/workspace/firewall/mcp_serversDeveloper+Registra um servidor (409 em nome duplicado).
PUT /api/workspace/firewall/mcp_serversDeveloper+Atualiza um servidor (id no corpo).
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+Soft-delete; libera o nome.
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+Probe de alcançabilidade + descoberta de ferramentas.
O proxy de SDK de um agente lê o registro de runtime sobre o token com escopo de gateway em GET /api/v1/firewall/mcp_servers (apenas servidores habilitados). Para como autenticar esse lado, veja autenticar o gateway MCP.
Por que conectar através do OrcaRouter afinal? Para que um lugar veja cada chamada de ferramenta — uma conexão, uma política, um log auditado, e credenciais injetadas no dispatch em vez de espalhadas pelas configs dos agentes. Leia segurança de agentes de IA e a ameaça de envenenamento de ferramentas MCP para a motivação.

​
Relacionados

Visão geral de segurança MCP

O modelo completo de governança de MCP, de ponta a ponta.

Firewall: Servidores MCP

O comportamento de runtime do gateway e os vereditos por chamada.

Autenticar o gateway

Cunhe e escope o token com o qual seu agente se conecta.

Checklist de confiança

Tudo a verificar antes de confiar em um novo servidor.