Firewall: MCP Server

Il Model Context Protocol (MCP) permette agli agent di chiamare tool ospitati da server esterni. È potente e pericoloso in egual misura: ogni MCP server a cui un agent si connette è un nuovo insieme di tool, credenziali e raggio d’azione di rete che nessuno ha revisionato. Il gateway MCP del Firewall mette un unico punto di strozzatura sottoposto ad audit davanti a tutti loro. Registri ogni MCP server una volta; il gateway espone i loro tool ai tuoi agent sotto un’unica connessione ed esegue ogni tools/call attraverso il motore del firewall prima che raggiunga il server reale.

1. Cosa ti dà la governance MCP

Un gateway, ogni server. Il tuo agent si connette a un endpoint. Il gateway aggrega i tool di ogni server registrato raggiungibile, con namespace <server>.<tool>, così github.create_issue e shell.exec compaiono affiancati sotto un’unica connessione MCP.
Policy su ogni chiamata. Ogni tools/call viene valutato prima dalla tua policy. Una chiamata bloccata torna al modello come un errore di tool (firewall deny: …), non un fallimento di trasporto, così l’agent può reagire invece di andare in crash. sanitize riscrive gli argomenti prima di inoltrare; pending_approval mette in attesa la chiamata.
Protetto da SSRF. Gli endpoint remoti sono validati rispetto alla policy SSRF del gateway — i range intranet e gli indirizzi dei metadati cloud sono bloccati, e l’IP di dial risolto viene ri-controllato per sconfiggere il DNS rebinding, su ogni hop inclusi i redirect.
Credenziali cifrate. I segreti di auth dei server sono cifrati a riposo e mascherati in lettura. Il gateway li inietta al momento del dispatch; non raggiungono mai il modello o il client.

2. Due tipi di server

Tipo	`endpoint`	Comportamento
BYO (bring-your-own)	Un URL streamable-HTTP	Il gateway fa da proxy del `tools/call` verso il tuo MCP server remoto.
Bundled	vuoto	L’MCP server in-process di OrcaRouter. Registrato così è visibile e governabile; non probeable separatamente.

3. Registrare un server

Un record di server porta:

Campo	Note
`name`	Chiave di business, unica per workspace, ≤ 128 caratteri. Nessun `.` — è il separatore di namespace `<server>.<tool>`.
`endpoint`	L’URL dell’MCP server (≤ 512 caratteri). Vuoto per il server bundled.
`auth_mode`	`none` (default), `bearer`, `oauth` o `basic`.
`auth_json`	Credenziali specifiche per modalità (vedi sotto). Richiesto ogni volta che `auth_mode` non è `none`.
`enabled`	Default `true`. Un server disabilitato viene omesso interamente dal gateway.
`status`	Raggiungibilità — `ok` (default), `degraded` o `down`. Impostato dal probing.

Forme delle credenziali per modalità:

// bearer
{ "token": "ghp_…" }
// oauth
{ "client_id": "…", "client_secret": "…", "token_url": "…" }
// basic
{ "username": "…", "password": "…" }
// none
""

Una richiesta di registrazione si presenta così:

curl https://api.orcarouter.ai/api/workspace/firewall/mcp_servers \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "endpoint": "https://api.githubcopilot.com/mcp",
    "auth_mode": "bearer",
    "auth_json": "{\"token\":\"ghp_x\"}",
    "enabled": true
  }'

Un nome duplicato nello stesso workspace restituisce HTTP 409 (lo stesso nome in un workspace diverso va bene).

I segreti non vengono mai memorizzati in chiaro. auth_json è cifrato a riposo con una chiave di segreti del workspace. Se quella chiave non è configurata, la scrittura viene rifiutata anziché persistere una credenziale non cifrata. In lettura, i segreti e l’endpoint vengono mascherati; rimanda indietro la maschera su un update per mantenere il valore memorizzato. Passare tra due modalità di auth con credenziali richiede un auth_json nuovo (il ciphertext è vincolato per forma alla sua modalità).

4. Probe — scopri i suoi tool

Prima di poter scrivere regole contro i tool di un server, devi conoscere i loro nomi. Fai il probe del server:

curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer sk-orca-..."

Il gateway esegue un initialize MCP + tools/list contro l’endpoint (usando le credenziali decifrate, con limite a 10s), registra lo status di raggiungibilità e un timestamp, e restituisce i tool pubblicizzati con i loro schemi di input:

{
  "status": "ok",
  "last_checked_at": 1700000000,
  "tools": [
    { "name": "create_issue", "description": "…", "input_schema": { } }
  ]
}

Ora puoi creare regole come tool_name_glob: github.* sapendo esattamente cosa accetta github.create_issue. Il server bundled (con endpoint vuoto) non è probeable e restituisce un 400.

5. Ciclo di vita e applicazione

Abilitato vs. disabilitato. Un server disabilitato viene rimosso dal registro a runtime — i suoi tool spariscono dal gateway e le sue credenziali non vengono mai decifrate. È l’interruttore di spegnimento.
Raggiungibilità. status (ok / degraded / down) riflette l’ultimo probe; un server irraggiungibile viene saltato quando il gateway costruisce il suo insieme di tool.
Verdetto per chiamata. Al dispatch il motore restituisce un verdetto per la specifica chiamata <server>.<tool> con i suoi argomenti:
- allow / audit → inoltrata (audit logga, consente comunque).
- sanitize → inoltrata con argomenti riscritti.
- deny / pending_approval / qualsiasi cosa sconosciuta → bloccata come un errore di tool. (Attraverso il gateway unificato, una chiamata held emerge come un errore permanente anziché passare l’id di approvazione — usa l’ hook di evaluate quando ti serve l’handshake di approvazione.)
L’eliminazione è una soft delete; lo slot del nome viene liberato immediatamente così puoi ri-registrare sotto lo stesso nome.

Ogni modifica invalida immediatamente la cache dei tool per-workspace del gateway, così un server appena registrato, disabilitato o ri-probato ha effetto alla connessione successiva anziché dopo un TTL di cache.

6. Collegare un client

Punta qualsiasi client MCP sull’endpoint del gateway con un token con scope firewall-gateway:

https://api.orcarouter.ai/api/v1/firewall/mcp

Il gateway parla streamable HTTP (messaggi POST, GET per lo stream SSE, DELETE per terminare una sessione) e si identifica come orcarouter-firewall-gateway. Pubblicizza i tool di ogni server abilitato e raggiungibile sotto il namespace <server>.<tool>, ri-esponendo verbatim lo schema di input di ciascun tool. Un token senza lo scope firewall-gateway riceve 403 — conia un token gateway dedicato per questo.

Riferimento API

Console (con scope a livello di workspace, RBAC)

Metodo & path	Ruolo	Scopo
`GET /api/workspace/firewall/mcp_servers`	Member	Elenca i server (segreti mascherati, endpoint redatto).
`GET /api/workspace/firewall/mcp_servers/:id`	Member	Singolo server, mascherato.
`POST /api/workspace/firewall/mcp_servers`	Developer+	Registra un server (409 su nome duplicato).
`PUT /api/workspace/firewall/mcp_servers`	Developer+	Aggiorna un server (id nel body).
`DELETE /api/workspace/firewall/mcp_servers/:id`	Developer+	Soft-delete; libera il nome.
`POST /api/workspace/firewall/mcp_servers/:id/probe`	Developer+	Probe della raggiungibilità + scoperta dei tool.

Gateway (token con scope firewall-gateway)

Metodo & path	Scopo
`ANY /api/v1/firewall/mcp`	L’endpoint unificato di dispatch del gateway MCP.
`GET /api/v1/firewall/mcp_servers`	Registro a runtime (auth decifrata, solo server abilitati) per un proxy SDK.
`POST /api/v1/firewall/evaluate`	Valuta un singolo `tools/call` prima di dispatcharlo tu stesso.

FAQ

Perché instradare l'MCP attraverso OrcaRouter?

Perché ci sia un unico posto che vede ogni chiamata a tool. Senza un gateway, ogni agent si connette a ogni MCP server direttamente — nessuna policy condivisa, nessun audit trail, nessuna protezione SSRF, e credenziali sparse nelle config degli agent. Il gateway centralizza tutto questo: una connessione, una policy, un log sottoposto ad audit, segreti cifrati iniettati al dispatch.

Cosa succede quando torna indietro una chiamata MCP bloccata?

Il modello la riceve come un errore di tool (firewall deny: <reason>), la stessa forma che otterrebbe da qualsiasi tool che fallisce. Questo lascia all’agent la possibilità di adattarsi — provare un approccio diverso, chiedere all’utente o fermarsi — invece di trattarla come un crash di trasporto.

Posso governare lo stesso tool in modo diverso per server?

Sì — è a questo che serve il namespace <server>.<tool>. Una regola con tool_name_glob: trusted.* può fare allow mentre community.* è in audit o pending_approval. Combinala con un glob sul nome della skill per uno scoping ancora più fine.

Il gateway protegge dall'SSRF?

Sì. Gli URL degli endpoint e i loro IP di dial risolti sono validati rispetto alla policy SSRF alla registrazione e su ogni hop di dispatch — i range intranet e l’indirizzo dei metadati cloud sono rifiutati, e l’IP risolto viene ri-controllato per sconfiggere il DNS rebinding. Abbinalo a una regola egress per governare dove i tool possono arrivare.

Vedi anche

Vuoi approfondire la sicurezza degli agent? Le guide Proteggi i tuoi agenti (Zero Trust) inseriscono questa feature in un workflow zero-trust.

Proteggi gli MCP server (Zero Trust)

Connetti, autentica e governa gli MCP server in una postura zero-trust.

Checklist di fiducia per MCP

Cosa verificare prima di fidarti di un MCP server di terze parti.

​1. Cosa ti dà la governance MCP

​2. Due tipi di server

​3. Registrare un server

​4. Probe — scopri i suoi tool

​5. Ciclo di vita e applicazione

​6. Collegare un client

​Riferimento API

​Console (con scope a livello di workspace, RBAC)

​Gateway (token con scope firewall-gateway)

​FAQ

​Vedi anche