MCP Gateway

• Name: the gateway key
• Servers: the linked MCP Servers, as a stack of server avatars, with a +N count 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

​

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 MCP Gateway.

General

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

Tools

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

Runtime limits

• Each cap listed under Runtime Limits, filled in with its default.

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).
• Tool naming: MCP_TOOL_NAMING_PREFIX_WITH_SERVER_KEY (Always prefix with server key) or MCP_TOOL_NAMING_PREFIX_ON_COLLISION (Prefix only 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.
  • Filter with Search servers and tools…. Each row shows N / M exposed tools; expand it for the tool list, Select all, and the N of M tools exposed counter.
  • Checkboxes apply immediately. Each tool carries an Open world, Read only, Idempotent, or Destructive badge.
  • The side panel shows Traffic, the Alias prefix, and Connection details.
• Clients: MCP clients authorized through OAuth, with the option to revoke their access.
• Settings: the MCP Gateway description, tool settings, plugins 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"]},
    },
)

​

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

​

Runtime Limits

​

Scope Tools

​

Give a Team its Own Tools

​

Per-User Tool Scoping

​

Connect a Client

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

​

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.

​

Client credentials

curl -X POST https://my.orq.ai/v2/auth/mcp/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://my.orq.ai/v3/mcp/<gateway-key> \
  -d "scope=mcp:tools mcp:resources"

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { ClientCredentialsProvider } from '@modelcontextprotocol/sdk/client/auth-extensions.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const authProvider = new ClientCredentialsProvider({
  clientId: process.env.ORQ_MCP_CLIENT_ID!,
  clientSecret: process.env.ORQ_MCP_CLIENT_SECRET!,
  expectedIssuer: 'https://my.orq.ai/v2/auth/mcp',
});

const transport = new StreamableHTTPClientTransport(
  new URL('https://my.orq.ai/v3/mcp/<gateway-key>'),
  { authProvider },
);
const client = new Client({ name: 'nightly-sync', version: '1.0.0' });
await client.connect(transport);

import { PrivateKeyJwtProvider } from '@modelcontextprotocol/sdk/client/auth-extensions.js';

const authProvider = new PrivateKeyJwtProvider({
  clientId: process.env.ORQ_MCP_CLIENT_ID!,
  privateKey: process.env.ORQ_MCP_CLIENT_PRIVATE_KEY!,
  algorithm: 'RS256',
  expectedIssuer: 'https://my.orq.ai/v2/auth/mcp',
});

import httpx

response = httpx.post(
    "https://my.orq.ai/v2/auth/mcp/token",
    auth=(CLIENT_ID, CLIENT_SECRET),
    data={
        "grant_type": "client_credentials",
        "resource": "https://my.orq.ai/v3/mcp/<gateway-key>",
        "scope": "mcp:tools mcp:resources",
    },
)
access_token = response.json()["access_token"]

​

Enterprise-managed authorization

curl -X POST https://my.orq.ai/v2/auth/mcp/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer \
  -d assertion=$ID_JAG \
  -d resource=https://my.orq.ai/v3/mcp/<gateway-key>

​

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}"
      }
    }
  }
}

​

Sessions

​

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