Vai al contenuto principale
Vuoi che i tuoi agent usino un Model Context Protocol (MCP) server — il tuo server remoto, o quello bundled — ma vuoi che ogni chiamata a tool che espone giri dietro un unico punto di strozzatura sottoposto ad audit. Il primo passo è registrare il server nel tuo workspace: un name, un endpoint, una modalità di auth, e le sue credenziali. Una volta registrato, il gateway MCP pubblicizza i suoi tool sotto un’unica connessione e valuta ogni tools/call attraverso la tua policy del firewall prima che raggiunga il server reale. Questa pagina copre quel singolo task — connettere e configurare un record di server. Per il comportamento a runtime del gateway e i verdetti per chiamata, vedi il riferimento MCP; per il quadro più ampio, parti dalla panoramica sulla sicurezza MCP.
La registrazione è un’azione di console (le route /api/workspace/firewall/* si autenticano con il tuo session / access token, non con una chiave relay sk-orca-…). Le scritture richiedono il ruolo Developer+; qualsiasi membro può elencare i server.

​
1. Come connettere un MCP server

Apri Firewall → MCP Servers nella console e aggiungi un server, o chiama direttamente la workspace API. Una registrazione porta quattro cose che contano:

name

Unico per workspace. Diventa il prefisso del namespace <server>.<tool>, quindi un nome duplicato nello stesso workspace viene rifiutato con HTTP 409.

endpoint

L’URL del tuo MCP server remoto. Lascialo vuoto per registrare il server bundled in-process così è visibile e governabile.

auth_mode

Come il gateway si autentica al tuo server: none, bearer, oauth o basic.

credenziali

Il segreto specifico per modalità. Memorizzato cifrato a riposo e mascherato in lettura — non raggiunge mai il modello o il client.
Un server parte enabled e viene rimosso interamente dal gateway nel momento in cui lo disabiliti — è l’interruttore di spegnimento, e le credenziali di un server disabilitato non vengono mai decifrate.

​
2. Un esempio concreto

Registra un MCP server GitHub remoto con un bearer token. Questa è una chiamata REST equivalente alla console; i nomi dei campi sono esattamente quelli che scrive il form. 
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
  }'
La forma della credenziale dipende da auth_mode:
{"token":"…"} — inviato come bearer token al tuo server.
{"access_token":"…"} — un access token statico che il gateway invia come header bearer. Lo scambio automatico client-credentials non è ancora supportato; senza un access_token memorizzato, un probe in modalità oauth fallisce anziché connettersi non autenticato.
{"username":"…","password":"…"}.
Una stringa vuota. Nessuna credenziale è allegata.
In lettura, sia la credenziale che l’endpoint sono mascherati — l’API restituisce placeholder sentinella, non i valori grezzi. Quando aggiorni un server, rimanda indietro quei placeholder invariati per mantenere i valori memorizzati; invia un auth_json nuovo solo quando stai effettivamente ruotando il segreto. Vedi rotazione delle credenziali.

​
3. Fai il probe della sua salute

Prima di poter scrivere regole del firewall contro i tool di un server, devi sapere che sono raggiungibili e come si chiamano. Fai il probe del server — il gateway esegue un handshake MCP initialize + tools/list usando le credenziali decifrate, registra la raggiungibilità, e restituisce i tool pubblicizzati: 
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": {} }
  ]
}
Lo status finisce nel record del server e guida l’indicatore di salute:
statusSignificato
okRaggiungibile; i tool sono serviti dal gateway.
degradedRaggiungibile, ma l’handshake è stato parziale.
downIrraggiungibile all’ultimo probe; il server viene saltato.
Un server down viene lasciato fuori quando il gateway costruisce il suo insieme di tool, così un’interruzione transitoria degrada con grazia invece di rompere il dispatch. Un probe restituisce il suo risultato indipendentemente dall’esito — un probe fallito torna come 200 con status: down e una motivazione ripulita, non un errore di trasporto.
Il server bundled in-process (endpoint vuoto) fa il dispatch localmente e non è probeable — fare il probe è rifiutato con un errore che spiega che la registrazione non ha endpoint. Fai il probe solo dei server BYO che hanno un URL.
Ogni modifica di registrazione invalida immediatamente la cache dei tool per-workspace del gateway, così un server appena connesso, disabilitato o ri-probato ha effetto alla connessione successiva anziché dopo una finestra di cache.

​
4. Dopo che è connesso

Una volta che un server è registrato e fa probe ok, i suoi tool sono governati:
  • Ogni chiamata viene valutata. Ogni tools/call passa attraverso la tua policy del firewall sulla superficie mcp prima di raggiungere il tuo server. Dai scope alle regole con tool_name_glob: github.* ora che conosci i nomi dei tool.
  • Blocca la superficie. Default su negare i tool che non hai esplicitamente consentito — vedi allow-list dei tool MCP.
  • Governa dove arriva. Scrivi una regola egress così un tool non può raggiungere host arbitrari.
  • Sorveglia i cambiamenti. Un server di cui ti fidavi può cambiare le sue definizioni di tool a posteriori; la difesa dai rug-pull segnala quel drift.

​
5. Riferimento API

Tutte le route della console hanno scope a livello di workspace e si autenticano con il tuo session / access token. Le letture di lista sono aperte a qualsiasi Member (segreti mascherati); ogni scrittura richiede Developer+.
Metodo & pathRuoloScopo
GET /api/workspace/firewall/mcp_serversMemberElenca i server (segreti + endpoint mascherati).
GET /api/workspace/firewall/mcp_servers/:idMemberSingolo server, mascherato.
POST /api/workspace/firewall/mcp_serversDeveloper+Registra un server (409 su nome duplicato).
PUT /api/workspace/firewall/mcp_serversDeveloper+Aggiorna un server (id nel body).
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+Soft-delete; libera il nome.
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+Probe della raggiungibilità + scoperta dei tool.
Il proxy SDK di un agent legge il registro a runtime tramite il token con scope gateway su GET /api/v1/firewall/mcp_servers (solo server abilitati). Per come autenticare quel lato, vedi autenticare il gateway MCP.
Perché connettersi attraverso OrcaRouter? Perché un unico posto veda ogni chiamata a tool — una connessione, una policy, un log sottoposto ad audit, e credenziali iniettate al dispatch anziché sparse nelle config degli agent. Leggi proteggere gli agent AI e la minaccia di avvelenamento dei tool MCP per la motivazione.

​
Correlati

Panoramica sulla sicurezza MCP

Il modello completo di governance MCP, da capo a fondo.

Firewall: MCP server

Il comportamento a runtime del gateway e i verdetti per chiamata.

Autenticare il gateway

Conia e dai scope al token con cui il tuo agent si connette.

Checklist di fiducia

Tutto da verificare prima di fidarti di un nuovo server.