---
title: "Create an MCP gateway"
method: POST
path: "/v2/mcp-gateways"
tags: ["MCP Gateway"]
---

# Create an MCP gateway

`POST /v2/mcp-gateways`

Creates a client-facing MCP gateway that links one or more synced upstream servers and exposes a unified MCP endpoint.

## Request body

- CreateMcpGatewayRequest
  - `key` string, required — Lowercase slug of letters, digits, hyphens and underscores, max 64 characters, unique per workspace; backs the gateway's public MCP URL.
  - `display_name` string, required — Human readable name shown in the workspace.
  - `description` string — Free-form note about what this gateway is for.
  - `server_links` McpGatewayServerLink[] — Upstream servers this gateway aggregates.
    - `mcp_server_id` string, required — Upstream MCP server this gateway aggregates.
    - `alias` string, required — Prefix used instead of the server key when namespacing this server's tool names. Must be unique within the gateway.
    - `enabled` boolean — Whether this link contributes tools to the gateway.
    - `tool_exposure` McpToolExposure, required
      - `mode` 'MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED' | 'MCP_TOOL_EXPOSURE_MODE_ALL' | 'MCP_TOOL_EXPOSURE_MODE_SELECTED' | 'MCP_TOOL_EXPOSURE_MODE_NONE', required
      - `read_only` boolean — Keeps only the tools the upstream annotates as read-only.
      - `tool_ids` string[] — `McpTool.id` values to expose when mode is SELECTED; a tool renamed upstream gets a new id on the next sync.
  - `tool_naming` 'MCP_TOOL_NAMING_UNSPECIFIED' | 'MCP_TOOL_NAMING_PREFIX_WITH_SERVER_KEY' | 'MCP_TOOL_NAMING_PREFIX_ON_COLLISION'
  - `mode` 'MCP_GATEWAY_MODE_UNSPECIFIED' | 'MCP_GATEWAY_MODE_CODE' | 'MCP_GATEWAY_MODE_DIRECT'
  - `sharing` Sharing — Sharing controls which projects in the workspace may use this entity and what they may do with it.
    - `all_projects` SharingAllProjects
    - `selected` SharingSelectedProjects
      - `project_ids` string[] — Projects allowed to use the entity. An empty list shares it with no project.
    - `allow_version_pin` boolean — Consuming projects may pin a specific version instead of tracking latest. Enforcement lives with the consuming reference.
    - `allow_fork` boolean — Projects may duplicate this entity into a detached project-owned copy.
    - `auto_grant_new_projects` boolean — New projects created after this sharing config is applied should receive access automatically. Enforcement lives with project creation and entity-specific adoption code.

## Response `200`

OK

- CreateMcpGatewayResponse
  - `mcp_gateway` McpGateway
    - `id` string — Unique identifier of the MCP gateway.
    - `key` string — Lowercase slug of letters, digits, hyphens and underscores, max 64 characters, unique per workspace; backs the gateway's public MCP URL.
    - `display_name` string — Human readable name shown in the workspace.
    - `description` string — Free-form note about what this gateway is for.
    - `server_links` McpGatewayServerLink[] — Upstream servers this gateway aggregates.
      - `mcp_server_id` string, required — Upstream MCP server this gateway aggregates.
      - `alias` string, required — Prefix used instead of the server key when namespacing this server's tool names. Must be unique within the gateway.
      - `enabled` boolean — Whether this link contributes tools to the gateway.
      - `tool_exposure` McpToolExposure, required
        - `mode` 'MCP_TOOL_EXPOSURE_MODE_UNSPECIFIED' | 'MCP_TOOL_EXPOSURE_MODE_ALL' | 'MCP_TOOL_EXPOSURE_MODE_SELECTED' | 'MCP_TOOL_EXPOSURE_MODE_NONE', required
        - `read_only` boolean — Keeps only the tools the upstream annotates as read-only.
        - `tool_ids` string[] — `McpTool.id` values to expose when mode is SELECTED; a tool renamed upstream gets a new id on the next sync.
    - `tool_naming` 'MCP_TOOL_NAMING_UNSPECIFIED' | 'MCP_TOOL_NAMING_PREFIX_WITH_SERVER_KEY' | 'MCP_TOOL_NAMING_PREFIX_ON_COLLISION'
    - `status` 'MCP_GATEWAY_STATUS_UNSPECIFIED' | 'MCP_GATEWAY_STATUS_ACTIVE' | 'MCP_GATEWAY_STATUS_DISABLED'
    - `public_url` string — Endpoint MCP clients connect to; relative when the deployment has no public base URL configured.
    - `created` string — ISO 8601 timestamp of when the gateway was created.
    - `updated` string — ISO 8601 timestamp of the most recent change to the gateway.
    - `exposed_tools_count` integer — Number of tools currently exposed across all enabled links.
    - `mode` 'MCP_GATEWAY_MODE_UNSPECIFIED' | 'MCP_GATEWAY_MODE_CODE' | 'MCP_GATEWAY_MODE_DIRECT'
    - `sharing` Sharing — Sharing controls which projects in the workspace may use this entity and what they may do with it.
      - `all_projects` SharingAllProjects
      - `selected` SharingSelectedProjects
        - `project_ids` string[] — Projects allowed to use the entity. An empty list shares it with no project.
      - `allow_version_pin` boolean — Consuming projects may pin a specific version instead of tracking latest. Enforcement lives with the consuming reference.
      - `allow_fork` boolean — Projects may duplicate this entity into a detached project-owned copy.
      - `auto_grant_new_projects` boolean — New projects created after this sharing config is applied should receive access automatically. Enforcement lives with project creation and entity-specific adoption code.

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/ed27dc516fb7/schema)