Skip to main content
Create a single client-facing MCP endpoint that bundles one or more MCP Servers. Clients connect to the MCP Gateway URL and get a unified tool surface without knowing individual server URLs or authentication details. The gateway acts as a virtual MCP server: it aggregates tools from multiple upstream servers behind one address.
This page covers MCP Gateways, client-facing endpoints that bundle upstream MCP Servers Orq connects to. This is a different feature from Orq’s own MCP server, which coding assistants connect to for workspace administration.
MCP Portal is the AI Gateway area that manages MCP Gateways and MCP Servers. Open it at AI Gateway > MCP Portal in the sidebar; the MCP Gateways tab lists every gateway in the workspace.

How It Works

A virtual MCP server is a single endpoint that gives clients access to tools from multiple upstream MCP Servers. The gateway aggregates these servers behind one address, handles authentication and routing, and resolves tool-name conflicts internally. Clients connect to one URL and see all linked tools as if they came from one provider.

Use Cases

  • Exposing multiple MCP servers through a single endpoint for clients that cannot manage multiple connections.
  • Aliasing server tools under consistent names so clients do not break when upstream tool names change.
  • Governing tool access per team: admins build an MCP Gateway from a selected subset of tools across several MCP Servers, so the Marketing team and the Research team can share the same servers while reaching different tools.

Set Up an MCP Gateway

Click Create MCP Gateway.
Create MCP Gateway form showing General section with Description and Key, and Tools section with Tool exposure mode and Tool naming

Create MCP Gateway form

General details
  • Description (optional): a note about what this MCP Gateway provides.
  • Key (required): a unique identifier. Used in the MCP Gateway URL. Cannot be changed after creation.
Tool settings
  • Tool exposure mode: how the MCP Gateway presents tools to connected clients. Code mode (default) exposes a single tool provided by the MCP Gateway that handles discovery and execution internally. Direct mode exposes each upstream tool individually.
  • Tool naming: how tool names are namespaced across servers. Always prefix with server key (default) prefixes all tools with the server’s key, or its alias if one is set per-link. Prefix on collision only prefixes conflicting names.
Click Create.

After Creation

Orq.ai redirects to the MCP Servers tab of the new MCP Gateway. Click + Add server to link any server already configured in MCP Servers. Only servers that have completed their initial sync can be linked.
Link only MCP Servers whose project access covers the MCP Gateway project access. An MCP Gateway on All projects therefore needs MCP Servers on All projects; change a server’s own scope from its Settings tab, as described in MCP Servers.
MCP Gateway detail page on the MCP Servers tab listing the tomtom-maps server expanded to show 3 of 18 tools exposed, with Traffic, Alias and Connection panels on the right

MCP Servers tab of an MCP Gateway with a linked server

The MCP Gateway detail page has four tabs:
  • Overview: traffic for the MCP Gateway and the Connect section with the command clients use to reach it.
  • MCP Servers: linked servers and the tools each one exposes. Select a tool checkbox to expose it through the MCP Gateway, or clear it to stop exposing it. Both take effect immediately, with no save action. The side panel shows Traffic for the selected server, its Alias (the prefix that namespaces the server’s tools), and its Connection details: server key, type, base URL, auth, and last sync time.
  • Clients: MCP clients authorized through OAuth, with the option to revoke their access.
  • Settings: the MCP Gateway description, tool settings, plugins, egress policy and runtime limits, and project access, editable after creation.

Project Access

An MCP Gateway is visible to the projects that may use it. The Access column of the gateway list shows the current scope: All Projects, No projects, or the shared project names. A new gateway is shared with every project.Change the scope on the Settings tab. Under Access control, pick All projects to share the gateway with the whole workspace, or Custom and set each project to Enabled or Disabled.

Disable and Re-enable a Gateway

status is MCP_GATEWAY_STATUS_ACTIVE (default) or MCP_GATEWAY_STATUS_DISABLED. A disabled gateway keeps its configuration and rejects every request, so a gateway that is serving the wrong tool surface can be switched off without deleting it. Clients receive a JSON-RPC error with code -32000 and the message gateway disabled. Set status back to MCP_GATEWAY_STATUS_ACTIVE to resume traffic.

Delete a Gateway

Delete a gateway from the Delete item in the gateway list row menu, the Delete item in the detail page overflow menu, or the Delete gateway button on the Settings tab. Each asks for confirmation.

Security Settings

The Settings tab holds three sections that govern what the MCP Gateway forwards and where it may connect. Runtime limits and egress policy also appear on the Create MCP Gateway form.

Plugins

Plugins attached to an MCP Gateway run on every tool call it serves.
Plugins section with an Add Plugin button and a Trace Scrubbing plugin listed with configure and remove icons

Plugins section on the MCP Gateway Settings tab

Click Add Plugin to attach one. Each listed plugin has a icon to configure it and a icon to remove it.
Plugins enforced at workspace level apply as a floor: an MCP Gateway can add plugins or tighten their settings, but cannot remove or weaken an enforced one.

Egress Policy

Controls which upstream addresses the MCP Gateway may reach when it calls linked MCP Servers.
Egress policy section with Allow private network switched off, Allow public internet switched on, and empty Allowed domains and Blocked domains text areas

Egress policy section on the MCP Gateway Settings tab

A call to a server that the policy rejects fails with the error code EGRESS_DENIED.

Runtime Limits

Caps applied to traffic through the MCP Gateway.

Toolsets

Toolsets are named collections of tools from one or more linked servers. Create a toolset from the MCP Gateway detail page by adding tools from linked servers. Attach a toolset to an Agent instead of listing individual tools. When the upstream server adds or removes tools, the toolset picks up the changes on the next sync.

Connect a Client

Any MCP-compatible client can reach the MCP Gateway, most often a coding agent such as Claude Code, Cursor, or Codex. See Coding Agents for the full list.
The examples below use https://my.orq.ai as the default host. For self-hosted or on-premise deployments, replace this with the base URL configured for your deployment. The API’s public_url field returns the full connect endpoint (which may be relative when no public base URL is configured).
Clients authenticate in one of two ways:
  • OAuth (default): the client signs in through the browser and receives a token scoped to this MCP Gateway and to the person who signed in. No credential is stored in the client configuration.
  • API key: the client sends an API key as a bearer token. Use this for headless or non-interactive clients.

OAuth

The Connect section on the Overview tab holds the command that registers the MCP Gateway with the agent. Run it as is:
Connect section showing an npx add-mcp command with the MCP Gateway URL and a name flag

Connect section on the MCP Gateway Overview tab

On first use the client receives a 401, discovers the Orq.ai authorization server from the response, and opens the browser. The approval page names the client and the MCP Gateway it is requesting access to. Click Approve to issue the token, or Deny to reject the request. The token grants the mcp:tools and mcp:resources scopes on this MCP Gateway only. Every authorized client appears on the Clients tab with the client name, when it authenticated, and who approved it. Choose Revoke access from a client’s menu to invalidate its token.
Replace <gateway-key> with the gateway key from the Connect section. Claude Code opens the browser for approval on first use. Confirm with claude mcp list.

API key

Pass an API key as a bearer token instead of signing in. Set ORQ_API_KEY, then register the MCP Gateway:
Set ORQ_API_KEY before running the command. Confirm with claude mcp list.

Monitor Usage

The Overview tab reports how clients use the MCP Gateway. It opens on the last 7 days, and every card compares that window against the one before it. Change the window with the time range picker in the top right.
MCP Gateway Overview showing Tool calls, Success, Errors and P95 latency cards above a Tool calls by outcome bar chart and a Tools leaderboard of the most called tools

MCP Gateway Overview tab over the last 7 days

Traffic and reliability breaks the same window down further:
  • Tool calls by outcome: call volume over time, split into successes and errors.
  • Tools leaderboard: the most called tools with their call count and P95 latency, listed under their namespaced names.

Audit Changes

Changes to the MCP Gateway are recorded in Audit Logs, so a change to the exposed tool surface can be traced back to whoever made it. Entries are written under two entity types: Filter by either entity type on the Audit Logs page to see only MCP Portal activity.