MCP Gateway

​

How It Works

​

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

Click Create MCP Gateway.

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.

Both key and display_name are required. The console has no display name field and sets display_name to the key.

cURL

TypeScript

Python

curl -X POST https://my.orq.ai/v2/mcp-gateways \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "support-tools",
    "display_name": "Support tools",
    "mode": "MCP_GATEWAY_MODE_CODE",
    "tool_naming": "MCP_TOOL_NAMING_PREFIX_WITH_SERVER_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).

See the full Create an MCP gateway API reference.

​

After Creation

• 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.

​

Roles and Permissions

​

Project Access

curl -X PATCH https://my.orq.ai/v2/mcp-gateways/<gateway-id> \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sharing": {
      "selected": { "project_ids": ["proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V"] }
    }
  }'

import { Orq } from "@orq-ai/node";

const client = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

await client.mcpGateways.update({
  id: "mcp_gateway_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
  updateMcpGatewayRequest: {
    sharing: {
      selected: { projectIds: ["proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V"] },
    },
  },
});

import os
from orq_ai_sdk import Orq

client = Orq(api_key=os.environ["ORQ_API_KEY"])

client.mcp_gateways.update(
    id="mcp_gateway_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    sharing={
        "selected": {"project_ids": ["proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V"]},
    },
)

​

Disable and Re-enable a Gateway

curl -X PATCH https://my.orq.ai/v2/mcp-gateways/<gateway-id> \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "MCP_GATEWAY_STATUS_DISABLED" }'

import { Orq } from "@orq-ai/node";

const client = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

await client.mcpGateways.update({
  id: "mcp_gateway_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
  updateMcpGatewayRequest: {
    status: "MCP_GATEWAY_STATUS_DISABLED",
  },
});

import os
from orq_ai_sdk import Orq

client = Orq(api_key=os.environ["ORQ_API_KEY"])

client.mcp_gateways.update(
    id="mcp_gateway_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
    status="MCP_GATEWAY_STATUS_DISABLED",
)

​

Delete a Gateway

curl -X DELETE https://my.orq.ai/v2/mcp-gateways/<gateway-id> \
  -H "Authorization: Bearer $ORQ_API_KEY"

import { Orq } from "@orq-ai/node";

const client = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

await client.mcpGateways.delete({
  id: "mcp_gateway_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
});

import os
from orq_ai_sdk import Orq

client = Orq(api_key=os.environ["ORQ_API_KEY"])

client.mcp_gateways.delete(id="mcp_gateway_01HZXW2K7Y8Q9M0N1P2R3S4T5V")

​

Security Settings

​

Plugins

​

Egress Policy

​

Runtime Limits

​

Toolsets

​

Scope Tools

​

Give a Team its Own Tools

1. Link the servers that provide the tools with + Add server on the MCP Servers tab.
2. Create a Toolset per team listing that team’s tools. See Toolsets.
3. Attach the toolset to the Agent the team runs, or set mcp_access.toolset_ids on the team’s API key.

​

Per-User Tool Scoping

​

Connect a Client

• OAuth (default): browser sign-in. Use this for interactive clients.
• API key: a bearer token in the client configuration. Use this for headless or non-interactive clients.

​

OAuth

1

Set up the client

The Connect section on the Overview tab shows the gateway key and this command. Copy it from there, or run it with <gateway-key> replaced:

npx add-mcp https://my.orq.ai/v3/mcp/<gateway-key> --name <gateway-key>

Register the MCP Gateway directly in the client, replacing <gateway-key> with the gateway key from the Connect section:

• Claude Code
• Cursor
• Codex
• VS Code

claude mcp add --transport http <gateway-key> https://my.orq.ai/v3/mcp/<gateway-key>

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:

{
  "mcpServers": {
    "<gateway-key>": {
      "url": "https://my.orq.ai/v3/mcp/<gateway-key>"
    }
  }
}

Save the configuration and complete the browser approval when Cursor prompts for it.

codex mcp add <gateway-key> --url https://my.orq.ai/v3/mcp/<gateway-key>

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:

{
  "servers": {
    "<gateway-key>": {
      "url": "https://my.orq.ai/v3/mcp/<gateway-key>",
      "type": "http"
    }
  }
}

VS Code opens the browser for approval on first connect.

2

Approve access

On first use the client 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.

• Discovery: an unauthenticated request to the gateway returns 401 with a WWW-Authenticate header 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 S256 challenge method, which binds the authorization code to the client that requested it.

​

API key

npx add-mcp https://my.orq.ai/v3/mcp/<gateway-key> \
  --name <gateway-key> \
  --header "Authorization: Bearer $ORQ_API_KEY"

claude mcp add --transport http <gateway-key> https://my.orq.ai/v3/mcp/<gateway-key> --header "Authorization: Bearer ${ORQ_API_KEY}"

{
  "mcpServers": {
    "<gateway-key>": {
      "url": "https://my.orq.ai/v3/mcp/<gateway-key>",
      "headers": {
        "Authorization": "Bearer YOUR_ORQ_API_KEY"
      }
    }
  }
}

codex mcp add <gateway-key> --url https://my.orq.ai/v3/mcp/<gateway-key> --bearer-token-env-var ORQ_API_KEY

{
  "inputs": [
    {
      "type": "promptString",
      "id": "orq-api-key",
      "description": "Orq.ai API Key",
      "password": true
    }
  ],
  "servers": {
    "<gateway-key>": {
      "url": "https://my.orq.ai/v3/mcp/<gateway-key>",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${input:orq-api-key}"
      }
    }
  }
}

​

Monitor Usage

• 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