- Name: the gateway key
- Servers: the linked MCP Servers, as a stack of server avatars, with a
+Ncount when the list is long - Exposed tools: how many tools the gateway exposes to clients
- Access: which projects can use the gateway
- Public URL: the endpoint clients connect to, with a copy control
- Created by: the member who created the gateway
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
- AI Studio
- API & SDK

Create MCP Gateway form
- Description (optional): a note about what this MCP Gateway provides.
- Key (required): lowercase letters, digits,
-and_, up to 64 characters. Forms the MCP Gateway URL and cannot change after creation.
- Tool exposure mode: how the MCP Gateway presents tools to connected clients. Code mode (default) exposes three meta-tools that handle discovery and execution internally (see Code mode). Direct 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 only on collision only prefixes conflicting names.
- Each cap listed under Runtime Limits, filled in with its default.
- Each guardrail listed under Guardrails.
After Creation
Orq.ai redirects to the Toolset 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. Through the API, PATCH /v2/mcp-gateways/ withserver_links replaces the linked servers. An empty server_links array changes nothing; send clear_server_links: true to unlink every server. The two fields cannot be combined.
expected_updated is the gateway’s current updated value. Send it whenever the update replaces server_links with a link that carries resource_exposure, or re-enables a link that exposes resources: without it the gateway rejects the write. A value that no longer matches the stored one is rejected with COMMON_ARTIFACT_STATE_CONFLICT, so read the gateway again and resend.

Toolset tab of an MCP Gateway with a linked server
- Overview: traffic for the MCP Gateway and the Connect section with the command clients use to reach it.
- Toolset: linked servers and the tools each one exposes, as a tree with a detail panel.
- Filter with Search servers and tools…. Each server row shows
N / Mtools exposed; expand it for the tool list and an toggle per tool. The toggle on the server row exposes or hides every tool currently listed. - Toggles apply immediately. Selecting a tool opens its description, input schema, and Open world, Read only, Idempotent, or Destructive badges in the detail panel.
- The server row menu carries Edit alias, Remove from gateway, and, when the upstream server added tools, Expose new tools and Hide new tools.
- Filter with Search servers and tools…. Each server row shows
- Skills: the skills the gateway serves as
SKILL.mdfiles, from the workspace Skills and from linked MCP Servers that publish skills, each with an exposure toggle. Select a file to preview its markdown. - Clients: MCP clients authorized through OAuth, with the option to revoke their access.
- Traces: the tool calls the gateway served, as individual traces scoped to this gateway.
- Settings: the MCP Gateway description and tool settings, runtime limits, plugins and guardrails, and project access, editable after creation.
Link Servers
Through the API, PATCH /v2/mcp-gateways/ withserver_links replaces the linked servers. An empty server_links array changes nothing; send clear_server_links: true to unlink every server. The two fields cannot be combined.
Each entry in server_links:
Roles and Permissions
Workspace roles decide who can view and manage the MCP Portal. MCP permissions follow the role and are not configurable per team or per gateway.Project Access
- AI Studio
- API & SDK
Delete a Gateway
- AI Studio
- API & SDK
Security Settings
The Settings tab holds the plugins, Guardrails, and runtime limits that govern what the MCP Gateway forwards and how much it forwards. The same guardrails and runtime limits fields appear on the Create MCP Gateway form.Plugins
Plugins attached to an MCP Gateway run on every tool call it serves. Guardrail Rules do not run on tool calls. To check tool traffic, use plugins and the gateway’s own Guardrails. Click + Plugin to attach one. Each listed plugin has a icon to configure it and an overflow menu to remove it.plugins[] array where each entry carries the plugin id and that plugin’s settings: PII Redaction takes entities, regions, entity_thresholds, threshold, language and on_failure; Trace Scrubbing takes mask.
Guardrails
Guardrails attached to an MCP Gateway check the tool calls it serves. Click + Guardrail to pick a system Guardrail or a guardrail-capable Evaluator, then set where it runs:- Input: checks the tool name and arguments before the call reaches the upstream MCP Server. Resource reads are checked at this stage too.
- Output: checks the tool result before it returns to the client.
- Both: runs at both stages.

Plugins and Guardrails sections on the MCP Gateway Settings tab
Tool call blocked by input guardrail "<name>"; the tool was not run. for input, or Tool result blocked by output guardrail "<name>"; the result was withheld. for output. If the check cannot be evaluated, the call fails closed with the JSON-RPC error guardrail evaluation failed.
Through the API, set guardrails on create or update. Each entry takes id, execute_on (input, output, or both), and optional sample_rate, is_guardrail, and options. On update, an omitted guardrails field leaves the list unchanged, and a non-empty list replaces it.
Runtime Limits
Caps applied to traffic through the MCP Gateway. Set them on the Create MCP Gateway form or on the Settings tab of an existing gateway: every limit is console-only, and no API field or SDK method sets them. Each field takes a whole number starting at0.
A gateway created through the API starts from the defaults in the table below, not from a blank record, with Max tools / gateway stored as 0. The request and response caps and the two request rates therefore apply immediately; only the tool cap waits to be set.
Exceeding either request rate returns 429 with a JSON-RPC error -32001 and the message rate limit exceeded. The window is rolling: each request counts against the limit for the next 60 seconds, with no reset on a minute boundary. The response carries no Retry-After header, so back off until earlier requests age out of the window.
200 response carrying the error.
tools/call result with isError: true and the upstream content.
Scope Tools
A gateway exposes one tool surface to every project it is shared with. Which tools a caller then reaches depends on the gateway’s exposure and on what the caller is bound to.New Tools
When a gateway serves only selected tools, a tool discovered by a later sync starts hidden. It appears first in the Toolset tab, marked New, and stays hidden until exposed there or from the sync summary.- Toggle the tool’s exposure in its Toolset row. To expose or keep hidden every new tool at once, open the server’s row menu and select Expose new tools or Hide new tools.
- When the server is linked to several gateways, the Tools updated summary lists each gateway with new tools and offers Expose, plus Review to open the gateway.
- A gateway that exposes all tools from a linked server includes a new tool as soon as the sync completes.
Code mode
A gateway in Code mode exposes three meta-tools instead of the upstream tools. Each takes one JSON object and returns one JSON object:execute runs at most 20 calls in one request and stops at a 1 MiB response. Inside a work unit the plan is capped at 165 seconds, so the gateway answers before the unit’s own wait ends.
Give a Team its Own Tools
Two teams reaching the same gateway see the same tools, so give a team its own tools with a gateway of its own: create an MCP Gateway for the team’s project, expose only the tools the team may call, and share it with that project alone. Other projects cannot reach it. Assign projects to teams in Settings → Organization → Teams. See Members and teams.Per-User Tool Scoping
Scoping tools to an individual user is not available. Individual tools cannot be granted to or withheld from a named user. Reach follows the gateway’s exposure and the projects the caller reaches. An OAuth token reaches one MCP Gateway as a whole rather than individual tools, and its scopes decide which methods it may call:mcp:tools covers tools, mcp:resources covers resources and skills. A call outside the token’s scopes returns 403 with an insufficient_scope challenge that names the missing scope.
For enterprise-managed servers, the identity provider also decides whether the user can access the upstream app. A tool can appear in the gateway’s catalog even when that provider denies the user’s call.
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. Protocol versionsextensions capability of initialize and server/discover:
2024-11-05: initialize replies with that revision, and the gateway answers notifications with 200 instead of the 202 that Streamable HTTP requires. A revision newer than the newest supported one returns UnsupportedProtocolVersion with the accepted revisions in supported.
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).- OAuth (default): browser sign-in. Use this for interactive clients.
- Client credentials: a pre-registered client gets short-lived tokens with no user present. Use this for services and automations.
- Enterprise-managed authorization: the company identity provider issues an ID-JAG that the client exchanges for a token, with no consent screen.
- API key: a bearer token in the client configuration. Use this for headless clients that cannot run an OAuth flow.
ENTERPRISE_AUTH_REAUTH_REQUIRED.
OAuth
OAuth is the default. The client signs in through the browser and receives a token scoped to this MCP Gateway and to the person who signed in, so no workspace API key is stored in the client configuration.Set up the client
<gateway-key> replaced:
Connect section on the MCP Gateway Overview tab
<gateway-key> with the gateway key from the Connect section:- Claude Code
- Cursor
- Codex
- VS Code
claude mcp list.Approve access

Approval page for an MCP client requesting access to a gateway

Clients tab on an MCP Gateway listing authorized MCP clients
- Discovery: an unauthenticated request to the gateway returns
401with aWWW-Authenticateheader pointing at the gateway’s metadata documents. The protected-resource document at/.well-known/oauth-protected-resource/v3/mcp/<gateway-key>names the authorization server; the authorization-server document at/.well-known/oauth-authorization-server/v2/auth/mcp, which serves every gateway, lists its endpoints. - Dynamic client registration: the client registers at the authorization server’s registration endpoint, so no client ID or secret needs provisioning in advance.
- Authorization code with PKCE: sign-in uses the authorization code flow with Proof Key for Code Exchange (PKCE) and the
S256challenge method, which binds the authorization code to the client that requested it.
mcp:tools and mcp:resources by default, on this MCP Gateway only. A client registered with the refresh_token grant refreshes it without another sign-in until access is revoked, and a refresh token lasts 7 days; any other client signs in again when the token expires. Each refresh replaces the refresh token; presenting a replaced one more than 60 seconds later revokes the client’s access, and the person signs in again.
Authorization server metadata
/.well-known/oauth-authorization-server/v2/auth/mcp advertises:
Client credentials
A pre-registered client authenticates as itself and receives a 10-minute access token bound to one MCP Gateway, without a browser or a refresh token. The client is its own principal and has the same access settings as an API key: project and permissions.Register the client
- Client secret (Basic) or Client secret (POST): the secret is shown once after creation. Use Rotate secret to replace it.
- Private key JWT: paste a JSON Web Key Set or a JWKS URL with the public keys. The client signs RFC 7523 assertions with
RS256,PS256orES256.
Request a token
resource:access_token, token_type, expires_in and the granted scope. Send the token as Authorization: Bearer <access_token> and request a new one before it expires.Authenticate with private_key_jwt
iss and sub set to the client ID, aud set to the token endpoint, iat, an exp within five minutes, and a unique jti; the header names the registered key in kid. Sign with RS256, PS256, or ES256.client_id to an HTTPS URL with a path; the URL must return a JSON document with the same client_id, a client_name, authorization_code in grant_types, redirect_uris, and token_endpoint_auth_method set to none or private_key_jwt. A private_key_jwt document carries exactly one of jwks or jwks_uri, and the document cannot contain client_secret.
With the TypeScript MCP SDK, the providers run discovery and the token request:
- Client secret
- Private key JWT
- Python
Enterprise-managed authorization
Available with the Enterprise Plan. The company identity provider decides which users may use which MCP clients. A client signed in through SSO asks the identity provider for an Identity Assertion JWT Authorization Grant (ID-JAG) and exchanges it at Orq.ai for a gateway token, so the user never sees the approval page.Connect the identity provider
Trust the identity provider
Configure the identity provider
aud: the authorization server issuer,https://my.orq.ai/v2/auth/mcp.resource: the gateway URL,https://my.orq.ai/v3/mcp/<gateway-key>, or omit it and sendresourcein the token request.client_id: the client’s ID at Orq.ai.
Exchange the ID-JAG
client_id and, with private_key_jwt, a client_assertion, and has no client secret. There is no refresh token: request a new ID-JAG when it expires.sub to an account the first time it sees it, and reuses that link afterwards. On first use the ID-JAG must carry email_verified: true and an email in one of the SSO connection’s allowed domains that matches an account already in the workspace. Orq.ai never creates accounts or memberships from an ID-JAG; a request with no matching member is rejected with invalid_grant. Changing the connection’s issuer clears its links.
Each ID-JAG is accepted once, must live 10 minutes or less, and is checked against the identity provider’s published keys.
Claude connectors
Claude Enterprise Managed Auth lets members of a Claude organization use an MCP Gateway as a connector without an approval page. Claude signs the ID-JAG under an issuer URL that belongs to that organization, so no SSO connection is needed.Verify the email domain
Copy the issuer URL
https://identity.anthropic.com/issuers/<issuer-id>.Register the issuer
Set the tenant ID
Run the connection test
https://my.orq.ai/v3/mcp/<gateway-key>, as a connector in Claude and click Run test under Connection status.email against the workspace’s members on every request, ignoring case, and rejects any address that is not on a verified domain. It does not use sub, and it never creates accounts or memberships.
Tokens last 15 minutes with no refresh token, and Claude requests a new ID-JAG when one expires. A user removed from the Claude organization keeps access until the current token expires.
API key
Pass an API key as a bearer token instead of signing in. Use a user key for a person, so access ends with their membership, or a service-account key for a deployment that must outlive the person who set it up. SetORQ_API_KEY, then register the MCP Gateway:
- Claude Code
- Cursor
- Codex
- VS Code
ORQ_API_KEY before running the command. Confirm with claude mcp list.Sessions
Each MCP request stands on its own. There is no gateway session for a client to initialize, keep alive, resume after a reconnect, or clean up.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 tab over the last 7 days
- 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.