--- title: "Create an MCP server" method: POST path: "/v2/mcp-servers" tags: ["MCP Gateway"] --- # Create an MCP server `POST /v2/mcp-servers` Creates a new upstream MCP server connection in the workspace. ## Request body - CreateMcpServerRequest - `key` string, required — Lowercase slug of letters, digits, hyphens and underscores, max 64 characters, unique per workspace; prefixes this server's tool names in gateways. - `display_name` string, required — Human readable name shown in the workspace. - `description` string — Free-form note about what this server is for. - `connection` McpConnection, required - `type` 'MCP_CONNECTION_TYPE_UNSPECIFIED' | 'MCP_CONNECTION_TYPE_HTTP' | 'MCP_CONNECTION_TYPE_SSE' | 'MCP_CONNECTION_TYPE_STDIO', required - `url` string, required — Upstream endpoint; must use the http or https scheme. - `auth` McpAuthConfig, required - `type` 'MCP_AUTH_TYPE_UNSPECIFIED' | 'MCP_AUTH_TYPE_NONE' | 'MCP_AUTH_TYPE_STATIC_HEADERS' | 'MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS' | 'MCP_AUTH_TYPE_PER_USER_OAUTH', required - `static_headers` McpHeaderSecret[] — Headers sent upstream on every request; at least one entry when type is STATIC_HEADERS. - `key` string — Header name sent to the upstream server. - `value` string — Header value; accepted on write and never returned. - `masked_value` string — Redacted preview of `value`, returned in its place. - `oauth` McpOAuthConfig - `client_id` string — OAuth client identifier presented to the upstream authorization server. - `client_secret` string — OAuth client secret; accepted on write and never returned. - `token_url` string — Token endpoint the gateway calls to mint upstream access tokens. - `scopes` string[] — Scopes requested when minting upstream access tokens. - `masked_value` string — Redacted preview of `client_secret`, returned in its place. - `default_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. - `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 - CreateMcpServerResponse - `mcp_server` McpServer - `id` string — Unique identifier of the MCP server. - `key` string — Lowercase slug of letters, digits, hyphens and underscores, max 64 characters, unique per workspace; prefixes this server's tool names in gateways. - `display_name` string — Human readable name shown in the workspace. - `description` string — Free-form note about what this server is for. - `connection` McpConnection - `type` 'MCP_CONNECTION_TYPE_UNSPECIFIED' | 'MCP_CONNECTION_TYPE_HTTP' | 'MCP_CONNECTION_TYPE_SSE' | 'MCP_CONNECTION_TYPE_STDIO', required - `url` string, required — Upstream endpoint; must use the http or https scheme. - `auth` McpAuthConfig - `type` 'MCP_AUTH_TYPE_UNSPECIFIED' | 'MCP_AUTH_TYPE_NONE' | 'MCP_AUTH_TYPE_STATIC_HEADERS' | 'MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS' | 'MCP_AUTH_TYPE_PER_USER_OAUTH', required - `static_headers` McpHeaderSecret[] — Headers sent upstream on every request; at least one entry when type is STATIC_HEADERS. - `key` string — Header name sent to the upstream server. - `value` string — Header value; accepted on write and never returned. - `masked_value` string — Redacted preview of `value`, returned in its place. - `oauth` McpOAuthConfig - `client_id` string — OAuth client identifier presented to the upstream authorization server. - `client_secret` string — OAuth client secret; accepted on write and never returned. - `token_url` string — Token endpoint the gateway calls to mint upstream access tokens. - `scopes` string[] — Scopes requested when minting upstream access tokens. - `masked_value` string — Redacted preview of `client_secret`, returned in its place. - `default_tool_exposure` McpToolExposure - `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. - `sync_state` McpSyncState - `status` 'SYNC_STATUS_UNSPECIFIED' | 'SYNC_STATUS_SYNCED' | 'SYNC_STATUS_FAILED' | 'SYNC_STATUS_PENDING' - `tools_total` integer — Tools in the catalog after the last sync. - `tools_added` integer — Tools the last sync discovered for the first time. - `tools_removed` integer — Tools the last sync no longer found upstream and marked MISSING. - `last_synced_at` string — ISO 8601 timestamp of the last sync attempt. - `errors` string[] — Failures reported by the last sync. - `tools` McpTool[] — Tool catalog discovered by the last successful `:sync`. - `name` string — Bare tool name as advertised by the upstream server. - `description` string — Tool description advertised upstream, passed through to MCP clients. - `input_schema` object — JSON Schema for the tool arguments, as advertised upstream. - `status` string — `ACTIVE`, or `MISSING` when the last sync no longer found the tool upstream. - `id` string — Assigned once on first discovery and preserved across sync. - `title` string — Human-readable label advertised upstream, when the server sends one. - `annotations` McpToolAnnotations — Hints claimed by the upstream server; the gateway does not enforce them. - `read_only` boolean — Upstream claims the tool does not modify state. - `destructive` boolean — Upstream claims the tool can perform destructive updates. - `idempotent` boolean — Upstream claims repeated calls with the same arguments have no extra effect. - `open_world` boolean — Upstream claims the tool reaches systems outside its own domain. - `created` string — ISO 8601 timestamp of when the server was created. - `updated` string — ISO 8601 timestamp of the most recent change to the server. - `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. - `template_variables` string[] — Names of `{{variable}}` placeholders found in the connection or auth config; supply values as `discovery_variables` on test, sync and tool calls. - `created_by_id` string — Account that created the server. --- [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/bfc2662b4090/schema)