Skip to main content

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 Auth Upstream credentials stay on the gateway. Clients only ever send their Guardway API key.

Authentication methods

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 dialog

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>. Use the combined URL when a team should get tools from several MCP servers through a single connection.
To check what a key can see, list its tools from the command line:
On the combined URL:
  • 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.
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.
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.
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.
  • API Keys — create keys and set their MCP access.
  • Security — guardrail rules, including rules that also run on MCP traffic.
  • Logs — MCP tool calls per server and tool.