Skip to main content
You want your agents to use a Model Context Protocol (MCP) server — your own remote server, or the bundled one — but you want every tool call it exposes to run behind a single audited choke point. The first step is to register the server in your workspace: a name, an endpoint, an auth mode, and its credentials. Once it’s registered, the MCP gateway advertises its tools under one connection and evaluates every tools/call through your firewall policy before it reaches the real server. This page covers that one task — connecting and configuring a server record. For the gateway’s runtime behavior and per-call verdicts, see the MCP reference; for the bigger picture, start at the MCP security overview.
Registration is a console action (the /api/workspace/firewall/* routes authenticate with your session / access token, not a relay sk-orca-… key). Writes require the Developer+ role; any member can list servers.

​
1. How to connect an MCP server

Open Firewall → MCP Servers in the console and add a server, or call the workspace API directly. A registration carries four things that matter:

name

Unique per workspace. It becomes the <server>.<tool> namespace prefix, so a duplicate name in the same workspace is rejected with HTTP 409.

endpoint

Your remote MCP server’s URL. Leave it empty to register the bundled in-process server so it’s visible and governable.

auth_mode

How the gateway authenticates to your server: none, bearer, oauth, or basic.

credentials

The mode-specific secret. Stored encrypted at rest and masked on read — it never reaches the model or the client.
A server starts enabled and is dropped from the gateway entirely the moment you disable it — that’s the off switch, and a disabled server’s credentials are never decrypted.

​
2. One concrete example

Register a remote GitHub MCP server with a bearer token. This is a console-equivalent REST call; the field names are exactly what the form writes. 
curl https://api.orcarouter.ai/api/workspace/firewall/mcp_servers \
  -H "Authorization: Bearer <your-session-or-access-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 credential shape depends on auth_mode:
{"token":"…"} — sent as a bearer token to your server.
{"access_token":"…"} — a static access token the gateway sends as a bearer header. Automatic client-credentials exchange is not yet supported; without a stored access_token, an oauth-mode probe fails rather than connecting unauthenticated.
{"username":"…","password":"…"}.
An empty string. No credentials are attached.
On read, both the credential and the endpoint are masked — the API returns sentinel placeholders, not the raw values. When you update a server, echo those placeholders back unchanged to keep the stored values; send a fresh auth_json only when you’re actually rotating the secret. See credential rotation.

​
3. Probe its health

Before you can write firewall rules against a server’s tools, you need to know they’re reachable and what they’re called. Probe the server — the gateway runs an MCP initialize + tools/list handshake using the decrypted credentials, records reachability, and returns the advertised tools: 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your-session-or-access-token>"

{
  "status": "ok",
  "last_checked_at": 1700000000,
  "tools": [
    { "name": "create_issue", "description": "…", "input_schema": {} }
  ]
}
The status lands in the server record and drives the health indicator:
statusMeaning
okReachable; tools are served by the gateway.
degradedReachable, but the handshake was partial.
downUnreachable on the last probe; the server is skipped.
A down server is left out when the gateway builds its tool set, so a transient outage degrades gracefully instead of breaking dispatch. A probe returns its result regardless of outcome — a failed probe comes back as 200 with status: down and a scrubbed reason, not a transport error.
The bundled in-process server (empty endpoint) dispatches locally and isn’t probeable — probing it is rejected with an error explaining the registration has no endpoint. You only probe BYO servers that have a URL.
Every registration change invalidates the gateway’s per-workspace tool cache immediately, so a newly connected, disabled, or re-probed server takes effect on the next connection rather than after a cache window.

​
4. After it’s connected

Once a server is registered and probing ok, its tools are governed:
  • Every call is evaluated. Each tools/call runs through your firewall policy on the mcp surface before it reaches your server. Scope rules by tool_name_glob: github.* now that you know the tool names.
  • Lock the surface down. Default to denying tools you didn’t explicitly allow — see allow-list MCP tools.
  • Govern where it reaches. Author an egress rule so a tool can’t fetch arbitrary hosts.
  • Watch for changes. A server you trusted can change its tool definitions after the fact; the rug-pull defense flags that drift.

​
5. API reference

All console routes are workspace-scoped and authenticate with your session / access token. List reads are open to any Member (secrets masked); every write requires Developer+.
Method & pathRolePurpose
GET /api/workspace/firewall/mcp_serversMemberList servers (secrets + endpoint masked).
GET /api/workspace/firewall/mcp_servers/:idMemberOne server, masked.
POST /api/workspace/firewall/mcp_serversDeveloper+Register a server (409 on duplicate name).
PUT /api/workspace/firewall/mcp_serversDeveloper+Update a server (id in body).
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+Soft-delete; frees the name.
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+Probe reachability + discover tools.
An agent’s SDK proxy reads the runtime registry over the gateway-scoped token at GET /api/v1/firewall/mcp_servers (enabled servers only). For how to authenticate that side, see authenticate the MCP gateway.
Why connect through OrcaRouter at all? So one place sees every tool call — one connection, one policy, one audited log, and credentials injected at dispatch instead of scattered across agent configs. Read securing AI agents and the MCP tool-poisoning threat for the motivation.

MCP security overview

The full MCP governance model, end to end.

Firewall: MCP servers

The gateway’s runtime behavior and per-call verdicts.

Authenticate the gateway

Mint and scope the token your agent connects with.

Trust checklist

Everything to verify before you trust a new server.