Bundle multiple MCP servers behind a single MCP Gateway endpoint with a unified tool surface for MCP-compatible clients.
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.
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.
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.
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.
Both key and display_name are required. The console has no display name field and sets display_name to the key.
mode and tool_naming mirror the form’s tool settings:
Tool exposure mode: MCP_GATEWAY_MODE_CODE (Code mode, the default) or MCP_GATEWAY_MODE_DIRECT (Direct mode).
Tool naming: MCP_TOOL_NAMING_PREFIX_WITH_SERVER_KEY (Always prefix with server key) or MCP_TOOL_NAMING_PREFIX_ON_COLLISION (Prefix on collision, the API default).
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 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.
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.
The sharing block on create or update replaces the scope. Send all_projects to share the gateway with every project, or selected.project_ids to list the projects that may use it. A Disabled project stops reaching the 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 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.
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 attached to an MCP Gateway run on every tool call it serves.
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.
Plugin
Behavior on the MCP Gateway
PII Redaction
Replaces personally identifiable information in free-text tool arguments with placeholders before the call reaches the upstream MCP Server, then restores the original values in the tool result. Arguments whose schema pins the value (enum, const, pattern, format) are forwarded unchanged. Configure the entities to mask, the detection threshold, and the failure behavior. See PII Redaction.
Trace Scrubbing
Masks the selected fields (system, input, output, metadata, variables, or all) in the traces the MCP Gateway stores for each tool call.
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.
Controls which upstream addresses the MCP Gateway may reach when it calls linked MCP Servers.
Egress policy section on the MCP Gateway Settings tab
Setting
Description
Allow private network
Permit outbound requests to private IP ranges, loopback and link-local addresses. Off by default, which blocks server-side request forgery. The target address is checked again when the connection is opened, so a DNS record that later resolves to a private address is still rejected.
Allow public internet
Permit outbound requests to the public internet. Disable to restrict the MCP Gateway to the allowed domains only.
Allowed domains
One domain per line. When set, only these domains are permitted.
Blocked domains
One domain per line. Takes precedence over allowed domains.
A call to a server that the policy rejects fails with the error code EGRESS_DENIED.
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.
Field
Description
Key
Unique identifier within the project.
Display name
Human-readable label.
Description
What the toolset covers.
Project
The project the toolset belongs to.
Tools
List of server + tool name pairs. Servers must be linked to this MCP Gateway.
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.
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.
Claude Code
Cursor
Codex
VS Code
claude mcp add --transport http <gateway-key> https://my.orq.ai/v3/mcp/<gateway-key>
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.
Add the MCP Gateway in Cursor Settings → Tools & MCP → New MCP Server and paste:
Replace <gateway-key> with the gateway key from the Connect section. Save the configuration and complete the browser approval when Cursor prompts for it.
Replace <gateway-key> with the gateway key from the Connect section, then run codex mcp login <gateway-key> to complete the browser approval.
Add the MCP Gateway with the MCP: Add Server command, select HTTP (HTTP or Server-Sent Events), and enter https://my.orq.ai/v3/mcp/<gateway-key> as the server URL. VS Code writes a .vscode/mcp.json:
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 tab over the last 7 days
Card
Description
Tool calls
Tool invocations routed through the MCP Gateway.
Success
Invocations that completed successfully.
Errors
Invocations that returned an error.
P95 latency
95th percentile duration of successful invocations.
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.
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:
Entity type
Recorded when
MCP Gateway
A gateway is created, updated, or deleted, including changes to its linked servers.
MCP Server
A server is created, updated, or deleted.
Filter by either entity type on the Audit Logs page to see only MCP Portal activity.