Passer au contenu principal
Un serveur MCP distant n’est qu’un endpoint HTTP sur lequel vos agents appellent des outils — et la plupart se trouvent derrière un token, un client OAuth, ou une auth basic. Quand vous enregistrez ce serveur derrière la passerelle MCP du Firewall, vous confiez le credential à OrcaRouter une fois, choisissez comment il s’authentifie, et la passerelle l’injecte au moment du dispatch. Le secret est chiffré au repos et ne voyage jamais vers le modèle ni vers le code de votre agent. Cette page couvre le volet authentification de l’enregistrement d’un serveur : les quatre formes de auth_mode et ce qu’il advient de votre credential. Pour tout ce que la passerelle fait à chaque tools/call une fois la connexion établie — politique par appel, namespacing, protection SSRF — voir la référence de la passerelle MCP.

​
1. Pourquoi s’authentifier à la passerelle

Sans passerelle, chaque agent qui parle à un serveur MCP porte sa propre copie du token de ce serveur, éparpillée dans les configs et les prompts. Routez le serveur à travers OrcaRouter à la place et le credential vit en exactement un seul endroit :
  • Un secret stocké par serveur. Vous enregistrez le credential une fois, sur l’enregistrement d’espace de travail. Les agents se connectent à la passerelle avec une clé OrcaRouter — ils ne voient jamais le token du serveur amont.
  • Chiffré au repos, masqué en lecture. Le credential est chiffré au stockage. Chaque fois que vous relisez le serveur via la console ou le SDK, le secret revient masqué — il n’existe aucune API qui le renvoie en clair.
  • Injecté au dispatch. La passerelle déchiffre le credential seulement au moment où elle transmet un tools/call au vrai serveur, puis l’attache à cette requête sortante. Il n’est jamais renvoyé au modèle ni au client.
Un credential que vous ne pouvez pas relire est une fonctionnalité, pas une lacune. Parce que les lectures sont toujours masquées, une session console ou un token SDK fuité ne peut pas exfiltrer les secrets de votre serveur MCP — il ne peut que les re-pointer ou en faire la rotation.

​
2. Choisir un auth_mode

Chaque enregistrement de serveur porte un auth_mode. C’est un ensemble fermé de quatre valeurs, et il décide de la forme du credential que vous fournissez dans auth_json :
Le serveur est ouvert (ou fait confiance à la passerelle par le réseau). Laissez auth_json vide. C’est la valeur par défaut quand vous ne définissez pas auth_mode.
Le cas le plus courant pour les serveurs MCP hébergés. Fournissez un token ; la passerelle l’envoie comme credential bearer à chaque appel.
{ "token": "ghp_…" }
Pour les serveurs protégés par OAuth. Fournissez un access_token que vous avez déjà émis ; la passerelle l’envoie comme credential bearer, exactement comme bearer. L’échange automatique de client-credentials (échangeant un client_id/client_secret contre un token frais) n’est pas encore disponible — un enregistrement oauth sans access_token est rejeté.
{ "access_token": "…" }
Auth HTTP basic.
{ "username": "…", "password": "…" }
auth_json est requis dès que auth_mode est autre chose que none. Enregistrer un serveur bearer/oauth/basic avec un credential vide est rejeté — la passerelle ne persistera pas une connexion à moitié configurée.

​
3. Enregistrer un serveur MCP sécurisé — un exemple

L’enregistrement d’un serveur MCP est une action console : il s’exécute sous votre token de session / d’accès contre /api/workspace/firewall/mcp_servers, et écrire un serveur requiert le rôle Developer+. (C’est différent de la clé relais sk-orca-… que vous utilisez pour les appels de modèle /v1/* — cette clé ne gère jamais la config d’espace de travail.) Enregistrez un serveur en auth bearer depuis la console firewall, ou avec votre token de session directement : 
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
  }'
Le name est unique par espace de travail (un doublon renvoie HTTP 409), et il ne peut pas contenir de . — ce caractère met les outils en namespace <server>.<tool>. À l’entrée, OrcaRouter chiffre auth_json et ne stocke que le chiffré. Quand vous relisez le serveur, vous obtenez la forme masquée.
Renvoyez la valeur masquée telle quelle sur une mise à jour pour conserver le secret stocké inchangé — envoyez un vrai auth_json seulement quand vous voulez réellement en faire la rotation. Voir rotation des credentials pour le flux de rotation.

​
4. Prouver que la connexion fonctionne

L’authentification n’est pas terminée tant que la passerelle ne peut pas réellement atteindre le serveur avec le credential que vous avez stocké. Sondez-le : 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your-session-token>"
La passerelle se connecte à l’endpoint en utilisant le credential déchiffré, liste les outils du serveur, et enregistre un status de joignabilité :
statusSignification
okJoint et authentifié ; outils découverts.
degradedJoignable mais pas pleinement sain.
downImpossible de se connecter ou de s’authentifier.
Un résultat down juste après l’enregistrement signifie presque toujours un mauvais credential ou un mauvais auth_mode — corrigez auth_json et sondez à nouveau. Le sondage est une action Developer+ ; le serveur in-process intégré n’a pas d’endpoint et n’est pas sondable.
Un serveur désactivé est l’interrupteur d’arrêt net : ses outils disparaissent de la passerelle et son credential n’est jamais déchiffré. Désactivez un serveur pendant que vous réglez son auth, puis réactivez-le une fois qu’un sondage revient ok.

​
5. Lire les serveurs depuis un agent

Vos agents ne lisent pas les credentials. Quand un proxy SDK a besoin du registre d’exécution, il appelle GET /api/v1/firewall/mcp_servers avec une clé scopée à la passerelle firewall — une clé dédiée, pas votre clé relais ni votre session. Ce chemin ne sert que les serveurs activés, et la passerelle reste propriétaire de l’injection des credentials de bout en bout. Connecter un agent à l’endpoint MCP unifié est couvert dans la référence de la passerelle.

​
6. Où aller ensuite

Connecter votre premier serveur

Le pas-à-pas complet de l’enregistrement, de l’espace de travail vide à un outil en service.

Faire la rotation des credentials

Échanger un secret fuité ou expirant sans couper la connexion.

Lister les outils MCP autorisés

Décider lesquels des outils d’un serveur vos agents peuvent réellement appeler.

Limiter l'egress

Contraindre où les outils d’un serveur sont autorisés à atteindre sur le réseau.
Pour les concepts derrière cela — comment la passerelle se place dans le chemin de la requête et pourquoi les credentials ne touchent jamais le modèle — voir Comment OrcaRouter inspecte et Sécuriser les agents IA. Pour les menaces que cela ferme, voir Empoisonnement d’outils MCP et exfiltration de données.