Skip to main content
A remote MCP server is just an HTTP endpoint your agents call tools on — and most of them sit behind a token, an OAuth client, or basic auth. When you register that server behind the Firewall’s MCP gateway, you hand OrcaRouter the credential once, pick how it authenticates, and the gateway injects it at dispatch time. The secret is encrypted at rest and never travels to the model or your agent code. This page covers the authentication side of registering a server: the four auth_mode shapes and what happens to your credential. For everything the gateway does to each tools/call after the connection is up — per-call policy, namespacing, SSRF protection — see the MCP gateway reference.

​
1. Why authenticate at the gateway

Without a gateway, every agent that talks to an MCP server carries its own copy of that server’s token, scattered across configs and prompts. Route the server through OrcaRouter instead and the credential lives in exactly one place:
  • One stored secret per server. You register the credential once, on the workspace record. Agents connect to the gateway with an OrcaRouter key — they never see the upstream server’s token.
  • Encrypted at rest, masked on read. The credential is encrypted when it’s stored. Every time you read the server back through the console or SDK, the secret comes back masked — there is no API that returns it in the clear.
  • Injected at dispatch. The gateway decrypts the credential only at the moment it forwards a tools/call to the real server, then attaches it to that outbound request. It is never echoed to the model or the client.
A credential you can’t read back is a feature, not a gap. Because reads are always masked, a leaked console session or SDK token can’t exfiltrate your MCP server secrets — it can only re-point or rotate them.

​
2. Pick an auth_mode

Every server registration carries an auth_mode. It’s a closed set of four values, and it decides the shape of the credential you supply in auth_json:
The server is open (or trusts the gateway by network). Leave auth_json empty. This is the default when you don’t set auth_mode.
The most common case for hosted MCP servers. Supply one token; the gateway sends it as a bearer credential on each call.
{ "token": "ghp_…" }
For OAuth-protected servers. Supply an access_token you already minted; the gateway sends it as a bearer credential, exactly like bearer. Automatic client-credentials exchange (trading a client_id/client_secret for a fresh token) is not available yet — an oauth registration without an access_token is rejected.
{ "access_token": "…" }
HTTP basic auth.
{ "username": "…", "password": "…" }
auth_json is required whenever auth_mode is anything other than none. Registering a bearer/oauth/basic server with an empty credential is rejected — the gateway won’t persist a half-configured connection.

​
3. Register a secure MCP server — one example

MCP server registration is a console action: it runs under your session / access token against /api/workspace/firewall/mcp_servers, and writing a server requires the Developer+ role. (This is different from the sk-orca-… relay key you use for /v1/* model calls — that key never manages workspace config.) Register a bearer-auth server from the firewall console, or with your session token directly: 
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
  }'
The name is unique per workspace (a duplicate returns HTTP 409), and it can’t contain a . — that character namespaces tools as <server>.<tool>. On the way in, OrcaRouter encrypts auth_json and stores only the ciphertext. When you read the server back, you get the masked form.
Echo the masked value straight back on an update to keep the stored secret unchanged — send a real auth_json only when you actually want to rotate it. See credential rotation for the rotation flow.

​
4. Prove the connection works

Authentication isn’t done until the gateway can actually reach the server with the credential you stored. Probe it: 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your-session-token>"
The gateway connects to the endpoint using the decrypted credential, lists the server’s tools, and records a reachability status:
statusMeaning
okReached and authenticated; tools discovered.
degradedReachable but not fully healthy.
downCould not connect or authenticate.
A down result right after registration almost always means a bad credential or the wrong auth_mode — fix auth_json and probe again. Probing is a Developer+ action; the bundled in-process server has no endpoint and isn’t probeable.
A disabled server is the clean off switch: its tools disappear from the gateway and its credential is never decrypted. Disable a server while you sort out its auth, then re-enable once a probe comes back ok.

​
5. Reading servers from an agent

Your agents don’t read credentials. When an SDK proxy needs the runtime registry it calls GET /api/v1/firewall/mcp_servers with a firewall-gateway-scoped key — a dedicated key, not your relay key and not your session. That path serves only enabled servers, and the gateway still owns credential injection end to end. Connecting an agent to the unified MCP endpoint is covered in the gateway reference.

​
6. Where to go next

Connect your first server

The full registration walkthrough, from empty workspace to a live tool.

Rotate credentials

Swap a leaked or expiring secret without dropping the connection.

Allow-list MCP tools

Decide which of a server’s tools your agents may actually call.

Limit egress

Constrain where a server’s tools are allowed to reach on the network.
For the concepts behind this — how the gateway sits in the request path and why credentials never touch the model — see How OrcaRouter inspects and Securing AI agents. For the threats this closes, see MCP tool poisoning and data exfiltration.