Vai al contenuto principale
Quando una chiave trapela, un collaboratore esterno se ne va, o un token semplicemente invecchia, devi sostituire la credenziale su un MCP server registrato senza smantellare il record del server, ri-scrivere le sue regole del firewall, o interrompere gli agent già connessi attraverso il gateway. È questo che è la rotazione: aggiorni l’auth su un server esistente, e il gateway MCP inizia a iniettare il nuovo segreto sul tools/call immediatamente successivo che fa il dispatch. L’auth di ogni server è cifrata a riposo e mascherata in lettura, così il token in chiaro non fa mai il round-trip di ritorno alla tua console, ai tuoi agent o al modello. La rotazione è un update di un singolo campo attraverso la console del workspace.

​
1. Perché la rotazione dei segreti MCP è un’azione a sé

Un MCP server registrato detiene tre cose che non vuoi perdere quando una credenziale cambia: un name unico per workspace (il namespace <server>.<tool> contro cui le tue regole fanno glob), un endpoint, e il suo insieme di tool scoperti. Eliminare e ri-creare il server per cambiare un token orfanerebbe ogni regola con scope <server>.* e forzerebbe un nuovo probe. La rotazione aggira tutto questo. Fai PUT dello stesso record di server con nuovo auth_json; tutto il resto — name, regole, tool scoperti — resta al suo posto.
Il gateway inietta le credenziali al momento del dispatch, decifrandole solo per fare la chiamata upstream. Un segreto ruotato ha effetto alla connessione successiva — OrcaRouter invalida la cache dei tool per-workspace a ogni modifica di server, quindi non c’è alcun TTL da attendere.

​
2. Una rotazione concreta

Diciamo che hai registrato un MCP server chiamato github con un bearer token, e quel token deve ruotare. Leggi prima il record corrente — la risposta maschera il segreto, così non stai mai maneggiando il vecchio testo in chiaro: 
# Configura dalla sessione di console (UserAuth), non da una chiave relay.
curl https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42 \
  -H "Authorization: Bearer <your console access token>"
Poi fai PUT dello stesso record con solo la nuova credenziale. Invia l’id nel body e il nuovo auth_json; il gateway lo ri-cifra prima che tocchi il database: 
curl -X PUT https://api.orcarouter.ai/api/workspace/firewall/mcp_servers \
  -H "Authorization: Bearer <your console access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 42,
    "auth_json": "{\"token\":\"ghp_NEW_token\"}"
  }'
I campi che ometti restano intatti — name, endpoint, auth_mode e enabled mantengono tutti i loro valori memorizzati. Il nuovo token è live sul prossimo tools/call.
Rimanda indietro la maschera per mantenere un segreto; invia un valore reale per cambiarlo. Se leggi il record e fai PUT di ritorno verbatim, il placeholder mascherato in auth_json viene riconosciuto come “mantieni ciò che è memorizzato” — il segreto non viene sovrascritto con la maschera. Solo un auth_json genuinamente nuovo ruota la credenziale.

​
3. Cambiare la modalità di auth, non solo il segreto

La rotazione copre anche lo spostamento di un server tra schemi di auth. L’insieme chiuso di valori auth_mode è:
Nessuna credenziale. auth_json è vuoto. Usalo per server MCP pubblici o fidati per rete.
{ "token": "…" } — inviato come header Authorization: Bearer.
{ "client_id": "…", "client_secret": "…", "token_url": "…" }. Se memorizzi un access_token statico nel JSON, il gateway lo invia come bearer token; lo scambio client-credentials in sé non è ancora eseguito, quindi un server che ha bisogno di uno scambio live fallirà finché non fornisci un token.
{ "username": "…", "password": "…" } — HTTP basic auth.
Passare tra due modalità con credenziali (es. bearer → basic) richiede l’invio di un auth_json nuovo nella stessa richiesta. Il ciphertext memorizzato è vincolato alla sua modalità originale, quindi il vecchio segreto non può essere reinterpretato sotto la nuova forma — fornisci la nuova credenziale, o l’update viene rifiutato.

​
4. Dopo aver ruotato: rifai il probe

Una credenziale ruotata cambia quali tool puoi raggiungere se il vecchio token era stato revocato. Fai il probe del server per confermare che la nuova auth funziona e rinfrescare il suo status di raggiungibilità: 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your console access token>"
Il probe esegue un handshake MCP con la nuova credenziale decifrata e riporta ok, degraded o down. Un fallimento di auth emerge qui anziché come un errore di tool confuso a metà run.

​
5. Ruoli e cosa resta mascherato

Ogni azione su questa pagina è una chiamata di console con scope a livello di workspace (/api/workspace/firewall/mcp_servers, UserAuth) ed è role-gated:
AzioneRuolo minimo
Leggere un server (segreto mascherato)Member
Ruotare / aggiornare / registrareDeveloper+
EliminareDeveloper+
Il testo in chiaro non viene mai restituito alla tua console. Le letture mascherano il segreto e redigono l’endpoint; il gateway è l’unica cosa che decifra una credenziale, e solo nel momento in cui contatta il server upstream. Il modello e i tuoi agent non vedono né il vecchio né il nuovo token.

​
6. Dove si colloca

La rotazione è un’operazione nella superficie di fiducia MCP più ampia. Una volta che i tuoi server sono connessi e autenticati, lo stesso gateway valuta ogni tools/call contro la tua policy del firewall prima che giri, applica la quarantena delle skill sopra, e governa il raggio d’azione in uscita.

Connetti un server

Registra un MCP server e fai il probe dei suoi tool.

Autentica

Scegli la modalità di auth giusta per ogni server.

Allow-list dei tool MCP

Dai scope a quali tool ogni server può esporre.

Limiti di egress

Governa dove le chiamate a tool possono arrivare.
Vedi Firewall: MCP Server per il ciclo di vita completo del server e la checklist di fiducia MCP per il passaggio di hardening end-to-end. La rotazione è anche una voce permanente contro l’avvelenamento dei tool MCP e l’esfiltrazione dei dati: una credenziale che puoi ruotare velocemente è una credenziale su cui un leak non può restare seduto.

​
FAQ

No. La rotazione cambia solo la credenziale. Il server mantiene il suo name, quindi ogni regola con scope <server>.* — e qualsiasi allow-list — resta attaccata.
Il nuovo segreto viene iniettato sul prossimo tools/call dispacciato. Non c’è alcun TTL di cache da attendere — OrcaRouter invalida la cache dei tool del workspace a ogni modifica di server.
No — ed è proprio il punto. Le letture restituiscono un segreto mascherato; il testo in chiaro è decifrato solo dal gateway al dispatch. Ruota inviando un nuovo valore, poi fai il probe per confermare che funziona.