Register MCP servers once, expose them through the gateway, and decide per API key or per application which tools each team can use.
What this is for
Configuration → MCP is where you register the Model Context Protocol servers your gateway exposes to AI clients such as Claude or VS Code / GitHub Copilot. Clients connect to the gateway instead of connecting to each MCP server directly. The gateway holds the upstream credentials, runs guardrails on tool calls, and logs every call.You don’t need an LLM provider to use it. An API key can be MCP-only: switch every provider off on the key while MCP enabled is on, or, with no provider configured, turn off its LLM access switch. The key then reaches only MCP servers, and gateway v0.5.40 and later refuse it on every LLM endpoint with HTTP 403. That way the gateway serves as a single, governed front door to your internal MCP servers.
OpenAI-style endpoints return the refusal with "code": "llm_access_disabled". /v1/messages answers in Anthropic’s error format instead: a permission_error whose message says the key is MCP-only. Gateways older than v0.5.40 refuse MCP-only keys on the main inference endpoints only, with provider_not_allowed (on /v1/messages, a permission_error saying the provider is not allowed); the Responses WebSocket (GET /v1/responses), files, batches, fine-tuning, vector stores, and assistants still accept them.
Options
Register MCP server
Register MCP server is a two-step dialog.Connection
Field
Notes
Select Template
Autofills a known integration. Leave it empty to configure manually.
Server Name
Display name (e.g. My MCP Server). Required.
Transport
STDIO, HTTP, or SSE.
Gateways
Leave every gateway unticked to deliver the server to all gateways in your organization. Tick one or more to deliver it only to those: clients of any other gateway do not see it, on either MCP URL.
Command / Arguments (comma-separated)
STDIO only (e.g. npx).
URL
HTTP / SSE only — the upstream server endpoint.
Auth
Field
Notes
Authentication
None, API Key, Bearer Token, Basic Auth, OAuth2 (client credentials), or OAuth sign-in (e.g. GitHub). Leave it as None for public servers or local development.
Header name
API Key only. X-API-Key, api-key, Ocp-Apim-Subscription-Key, or a custom header.
Client certificate (mTLS)
Optional client certificate and private key (PEM), plus an optional server CA certificate and server name, for upstreams that require mutual TLS or use a private CA.
Additional Headers (JSON)
Extra headers sent to the upstream on every request.
Description
Free-form notes.
Upstream credentials stay on the gateway. Clients only ever send their Guardway API key.
Authentication methods
Method
What the gateway sends upstream
None
No auth header. Public servers and local development.
API Key
The key verbatim in the Header name you choose. Choose Authorization to send a raw Authorization: <key> header with no Bearer prefix — this is what Freshservice and some other servers expect.
Bearer Token
Authorization: Bearer <token>.
Basic Auth
Authorization: Basic base64(user:pass). (Freshservice also accepts its API key this way: username = the key, password = X.)
OAuth2 (client credentials)
The gateway exchanges a client_id/client_secret at the token URL and sends Authorization: Bearer <token>, renewing it before it expires. A machine-to-machine grant, not a per-person sign-in. Needs gateway v0.5.33 or later.
OAuth sign-in
A person signs in at the provider once; the gateway holds and renews the token. See Sign in to a server.
Freshservice. Register an HTTP server with the URL https://<your-domain>.freshservice.com/mcp. For API-key access choose API Key, set Header name to Authorization, and paste your Freshservice API key (it is sent verbatim, with no Bearer prefix). For per-person access choose OAuth sign-in instead (needs an Enterprise plan and an agent account). The register dialog’s Freshservice template fills these in.
Tools
After a server is registered, the gateway discovers its tools automatically. Open the server and use Discover Tools in the Tools section to refresh the list. Turning a tool off in the Allow column hides it from every key.
Server detail
Opening a server shows its detail panel:
Tools Summary — Discovered tools, Allowed tools, Total scans, and Last scan.
Per tool — each discovered tool with a risk badge and its recent call count. (No tools discovered yet. until the first discovery completes; the first few are shown, with the rest in the edit view.)
Findings — a rollup of the server’s MCP security findings by severity: critical, high, medium, low.
How to configure
1
Open Configuration → MCP
Open Configuration → MCP from the dashboard sidebar and click Register MCP server.
Register MCP server
2
Set the connection
Pick a Template or fill Server Name, Transport, and the URL (or Command for STDIO).
3
Set authentication
Choose how the gateway authenticates to the upstream server and provide the credentials. Click Register Server.
4
Check the tools
Open the server. The Tools section lists what the gateway discovered. Turn off any tool that no one should use.
Sign in to a server (OAuth)
Some servers authenticate a person, not a shared key. The gateway signs in on the organization’s behalf and holds the token (GitHub’s MCP server, Freshservice’s OAuth mode, Atlassian, Linear, Notion, and others).
1
Register with OAuth sign-in
Register the server (HTTP) and set Authentication to OAuth sign-in. Most servers need nothing else: the gateway discovers the authorization server and registers itself automatically (RFC 7591 dynamic client registration).
2
Connect
Save, then click Connect on the server and complete the provider’s sign-in in the popup. The gateway stores the token, renews it, and sends it upstream. One sign-in serves the whole organization.
If a provider does not register clients automatically, create an OAuth app there with this callback URL and enter its Client ID and Client secret in the server’s auth settings:
The gateway requests the scopes the server asks for (the scope in its 401 challenge, otherwise everything it advertises) and adds offline_access when the server offers it, so it can renew the token. To pin specific scopes, set Scope in the auth settings.
Connect a client
The gateway serves MCP on two kinds of URL. Both authenticate with an API key from API Keys, sent as Authorization: Bearer <key>.
URL
What the client sees
<gateway URL>/mcp/<server>
One registered server. The server’s edit panel shows this URL and ready-made client snippets under Client Configuration.
<gateway URL>/mcp
Every server the key may use, combined into one MCP server. Each tool name is prefixed with its server’s slug: <server-slug>__<tool>, for example crm__read_data. The slug is the last part of the server’s own URL.
Use the combined URL when a team should get tools from several MCP servers through a single connection.
tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/read, initialize and ping are supported. Prompts are prefixed like tools; resources keep their URIs. For any other MCP method, connect to the server’s own URL.
One slow or unreachable server does not fail the list: the gateway returns what the other servers answered. Each server has 25 seconds to answer (GUARDWAY_MCP_AGGREGATE_UPSTREAM_TIMEOUT_SECONDS).
The separator between slug and tool is __. To use another, set GUARDWAY_MCP_AGGREGATE_SEPARATOR on the gateway; every client then uses the new names.
A GET on <gateway URL>/mcp lists the servers the key may use, with each one’s slug, status, tool count and own URL.
After changing which tools a key can use, restart or reconnect MCP in the client so it fetches the new tool list.
Give each team its own set of tools
The API key a client connects with decides which servers and tools it sees. Tools a key may not use are left out of the tool list, and calls to them are refused.For example, two MCP servers:
CRM has read_data and write_db.
Blog has read_posts and publish_post.
Team
Should get
HR
CRM read_data, Blog read_posts and publish_post
Sales
CRM read_data and Blog read_posts only
There are two ways to set this up. Both can be combined, and a tool is available only when every rule that applies allows it.
Per API key
Per application
Best when each team has one key.
1
Create a key per team
Open Configuration → API Keys and create a key for each team (e.g. hr-mcp, sales-mcp). Only the name is required. To make it MCP-only, switch every provider off on the Access step and leave MCP enabled on. With no provider configured, turn off LLM access instead.
2
Scope the key's MCP access
On the key’s Access step, keep MCP enabled on and set MCP access mode to Allow list. In a key’s edit panel, these settings are under MCP access, and the mode is labeled Access mode.
3
Switch on the tools the team may use
Expand each server and switch on only the team’s tools: for sales-mcp, read_data under CRM and read_posts under Blog. Servers with at least one switched-on tool are added to the key’s allowed servers. A server in Allowed servers with no per-tool rules exposes all of its tools; switch specific tools off to restrict it. To take a server away from the key, switch off all of its tools, and remove it from Allowed servers if it is still listed there.
4
Connect the client
Give each team the combined /mcp URL and its own key.
Per-tool switches on a key are enforced by gateway v0.5.39 and later. On older gateways, use an application policy (next tab) for tool-level rules. A key’s rules name servers, and renaming a server does not rewrite them: re-check keys after renaming a server.
Best when a team or agent uses several keys, or when you want one place to manage its rules.
1
Register the application
Open Security → Apps, click New application, and enter a Name (e.g. HR) and Slug.
2
Bind the keys
In Configuration → API Keys, set each of the team’s keys’ Application field to that application. Requests made with those keys inherit the application’s policy.
3
Write the policy
Open Security → Policy, click New policy, and set Application scope to the application. In the MCP tools section, set MCP tool calls to On: allow MCP (subject to rules) and add Tool rules: one row per server with its Allow tools (e.g. server CRM, allow read_data). Use * as the server to apply a rule to every server. A deny always wins, and a non-empty allow list is exclusive.
4
Save
Click Save & apply. The policy reaches live traffic within about a minute.
An application policy can only narrow what a key already allows.
A call to a tool the key may not use, on a server it may use, is refused with HTTP 403 and {"error": "tool not permitted by policy", "tool": "<tool>"}. The refusal is recorded in the gateway’s audit log, which is stored locally on the gateway, and fires the MCP Tool Denied (mcp.tool_denied) webhook event.A server the key or its application may not use at all is refused differently, and does not fire MCP Tool Denied:
On the combined URL, its tools are not listed. A call to one returns HTTP 200 with a JSON-RPC error -32602 (unknown namespace), and no webhook event fires.
On the server’s own URL, the gateway returns HTTP 403 with mcp_access_denied (the key’s rules) or mcp_server_not_allowed_for_application (the application policy), and fires Permission Denied (audit.permission_denied).
Tool calls made through the gateway, on either URL, show up in Logs → MCP.