Vai al contenuto principale
Un server MCP remoto è solo un endpoint HTTP su cui i tuoi agent chiamano tool — e la maggior parte di essi sta dietro un token, un client OAuth o basic auth. Quando registri quel server dietro il gateway MCP del Firewall, consegni a OrcaRouter la credenziale una volta, scegli come si autentica, e il gateway la inietta al momento del dispatch. Il segreto è cifrato a riposo e non viaggia mai verso il modello o il codice del tuo agent. Questa pagina copre il lato autenticazione della registrazione di un server: le quattro forme di auth_mode e cosa succede alla tua credenziale. Per tutto ciò che il gateway fa a ogni tools/call dopo che la connessione è attiva — policy per chiamata, namespacing, protezione SSRF — vedi il riferimento del gateway MCP.

​
1. Perché autenticare al gateway

Senza un gateway, ogni agent che parla con un MCP server porta la propria copia del token di quel server, sparsa tra config e prompt. Instrada invece il server attraverso OrcaRouter e la credenziale vive in esattamente un posto:
  • Un segreto memorizzato per server. Registri la credenziale una volta, sul record del workspace. Gli agent si connettono al gateway con una chiave OrcaRouter — non vedono mai il token del server upstream.
  • Cifrata a riposo, mascherata in lettura. La credenziale è cifrata quando viene memorizzata. Ogni volta che rileggi il server attraverso la console o l’SDK, il segreto torna mascherato — non c’è API che lo restituisce in chiaro.
  • Iniettata al dispatch. Il gateway decifra la credenziale solo nel momento in cui inoltra un tools/call al server reale, poi la allega a quella richiesta in uscita. Non viene mai rimandata al modello o al client.
Una credenziale che non puoi rileggere è una feature, non una lacuna. Poiché le letture sono sempre mascherate, una sessione di console o un token SDK trapelato non può esfiltrare i segreti del tuo server MCP — può solo ri-puntarli o ruotarli.

​
2. Scegli un auth_mode

Ogni registrazione di server porta un auth_mode. È un insieme chiuso di quattro valori, e decide la forma della credenziale che fornisci in auth_json:
Il server è aperto (o si fida del gateway per rete). Lascia auth_json vuoto. Questo è il default quando non imposti auth_mode.
Il caso più comune per i server MCP hosted. Fornisci un token; il gateway lo invia come credenziale bearer a ogni chiamata.
{ "token": "ghp_…" }
Per i server protetti da OAuth. Fornisci un access_token che hai già coniato; il gateway lo invia come credenziale bearer, esattamente come bearer. Lo scambio automatico client-credentials (scambiare un client_id/client_secret per un token fresco) non è ancora disponibile — una registrazione oauth senza un access_token viene rifiutata.
{ "access_token": "…" }
HTTP basic auth.
{ "username": "…", "password": "…" }
auth_json è richiesto ogni volta che auth_mode è qualcosa di diverso da none. Registrare un server bearer/oauth/basic con una credenziale vuota viene rifiutato — il gateway non persiste una connessione configurata a metà.

​
3. Registrare un server MCP sicuro — un esempio

La registrazione di un server MCP è un’azione di console: gira sotto il tuo session / access token contro /api/workspace/firewall/mcp_servers, e scrivere un server richiede il ruolo Developer+. (Questo è diverso dalla chiave relay sk-orca-… che usi per le chiamate ai modelli /v1/* — quella chiave non gestisce mai la config del workspace.) Registra un server con auth bearer dalla console del firewall, o direttamente con il tuo session token: 
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
  }'
Il name è unico per workspace (un duplicato restituisce HTTP 409), e non può contenere un . — quel carattere mette a namespace i tool come <server>.<tool>. In ingresso, OrcaRouter cifra auth_json e memorizza solo il ciphertext. Quando rileggi il server, ottieni la forma mascherata.
Rimanda indietro il valore mascherato così com’è su un update per mantenere il segreto memorizzato invariato — invia un auth_json reale solo quando vuoi effettivamente ruotarlo. Vedi rotazione delle credenziali per il flusso di rotazione.

​
4. Dimostra che la connessione funziona

L’autenticazione non è finita finché il gateway non riesce effettivamente a raggiungere il server con la credenziale che hai memorizzato. Fai il probe: 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your-session-token>"
Il gateway si connette all’endpoint usando la credenziale decifrata, elenca i tool del server, e registra uno status di raggiungibilità:
statusSignificato
okRaggiunto e autenticato; tool scoperti.
degradedRaggiungibile ma non del tutto sano.
downImpossibile connettersi o autenticarsi.
Un risultato down subito dopo la registrazione quasi sempre significa una credenziale errata o l’auth_mode sbagliato — correggi auth_json e rifai il probe. Fare il probe è un’azione Developer+; il server bundled in-process non ha endpoint e non è probeable.
Un server disabilitato è l’interruttore di spegnimento pulito: i suoi tool spariscono dal gateway e la sua credenziale non viene mai decifrata. Disabilita un server mentre sistemi la sua auth, poi ri-abilitalo quando un probe torna ok.

​
5. Leggere i server da un agent

I tuoi agent non leggono credenziali. Quando un proxy SDK ha bisogno del registro a runtime chiama GET /api/v1/firewall/mcp_servers con una chiave con scope firewall-gateway — una chiave dedicata, non la tua chiave relay e non la tua sessione. Quel path serve solo i server abilitati, e il gateway detiene comunque l’iniezione delle credenziali da capo a fondo. Collegare un agent all’endpoint MCP unificato è coperto nel riferimento del gateway.

​
6. Dove andare dopo

Connetti il tuo primo server

La procedura completa di registrazione, da workspace vuoto a tool live.

Ruota le credenziali

Sostituisci un segreto trapelato o in scadenza senza far cadere la connessione.

Allow-list dei tool MCP

Decidi quali dei tool di un server i tuoi agent possono davvero chiamare.

Limita l'egress

Vincola dove i tool di un server possono arrivare in rete.
Per i concetti dietro tutto questo — come il gateway si colloca nel percorso della richiesta e perché le credenziali non toccano mai il modello — vedi Come OrcaRouter ispeziona e Proteggere gli agent AI. Per le minacce che chiude, vedi Avvelenamento dei tool MCP e esfiltrazione dei dati.