--- title: "List MCP servers" method: GET path: "/v2/mcp-servers" tags: ["MCP Gateway"] --- # List MCP servers `GET /v2/mcp-servers` ## Request - Base URL: `https://my.orq.ai` - URL: `https://my.orq.ai/v2/mcp-servers` - Auth: HTTP bearer Returns a paginated list of MCP servers in the workspace. ## Query parameters - `limit` integer - `starting_after` string - `ending_before` string - `search` string - `all_accessible_projects` boolean ## Response `200` OK - ListMcpServersResponse - `object` string: Always "list". - `data` McpServer[]: MCP servers on the current page. - `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_HTTP' | 'MCP_CONNECTION_TYPE_SSE' | 'MCP_CONNECTION_TYPE_STDIO' | 'MCP_CONNECTION_TYPE_OPENAPI', required - `url` string, required: Upstream endpoint; must use the http or https scheme. - `auth` McpAuthConfig - `type` 'MCP_AUTH_TYPE_NONE' | 'MCP_AUTH_TYPE_STATIC_HEADERS' | 'MCP_AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS' | 'MCP_AUTH_TYPE_PER_USER_OAUTH' | 'MCP_AUTH_TYPE_ENTERPRISE_MANAGED', 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: McpOAuthConfig is the OAuth client orq presents to the upstream authorization server for OAUTH_CLIENT_CREDENTIALS, PER_USER_OAUTH and ENTERPRISE_MANAGED. - `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 for OAUTH_CLIENT_CREDENTIALS; PER_USER_OAUTH and ENTERPRISE_MANAGED discover it from `resource`. - `scopes` string[]: Scopes requested when minting upstream access tokens. - `masked_value` string: Redacted preview of `client_secret`, returned in its place. - `issuer` string: Exact authorization-server issuer; pins discovery for PER_USER_OAUTH and ENTERPRISE_MANAGED. - `resource` string: Protected resource identifier; defaults to the upstream connection URL. - `enterprise` McpEnterpriseAuthConfig: McpEnterpriseAuthConfig is superseded by McpOAuthConfig: ENTERPRISE_MANAGED servers read and write `oauth`. It is still accepted on write and mirrored on read. - `resource` string: RFC 9728 resource identifier the tokens are bound to; defaults to the connection URL. - `client_id` string: OAuth client identifier registered at the upstream authorization server. - `client_secret` string: OAuth client secret; accepted on write and never returned. - `masked_value` string: Redacted preview of `client_secret`, returned in its place. - `scopes` string[]: Scopes requested when redeeming the identity assertion grant. - `default_tool_exposure` McpToolExposure - `mode` '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. - `excluded_tool_ids` string[]: `McpTool.id` values deliberately left unexposed when mode is SELECTED; an active tool in neither list is new to this selection. - `sync_state` McpSyncState - `status` '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. - `skills_total` integer: Skills in the catalog after 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; unset when the upstream sent no hint, which MCP reads as true. - `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; unset when the upstream sent no hint, which MCP reads as true. - `title` string: Display name the upstream sent in its annotations. - `http_operation` McpHttpOperation - `method` string: HTTP method, upper case. - `path` string: Path template relative to the server base URL. - `icons` McpIcon[]: Icons advertised by the upstream tool. - `src` string: Icon URI, including HTTPS URLs and base64 data URIs. - `mime_type` string: Optional MIME type override. - `sizes` string[]: Supported sizes such as "48x48" or "any". - `theme` string: Optional background theme this icon was designed for. - `output_schema` object: JSON Schema for the tool's structured result, as advertised upstream; omitted when the upstream sent an invalid one. - `meta` object: Tool `_meta` advertised upstream. - `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 the latest version. - `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. - `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. - `skills` McpSkill[]: Skills the upstream publishes through the MCP Skills extension, discovered by the last successful `:sync`. - `uri` string: Resource URI of the skill's `SKILL.md` on the upstream server. - `name` string: Skill name from the `SKILL.md` frontmatter. - `description` string: Skill description from the `SKILL.md` frontmatter. - `frontmatter` object: Full `SKILL.md` frontmatter as published upstream. - `files` McpSkillFile[]: Manifest of the skill's files; empty when the skill is dynamic. - `uri` string: Resource URI of the file on the upstream server. - `digest` string: SHA-256 digest of the file's raw bytes, formatted as `sha256:{hex}`. - `size` string: Length in bytes of the file's raw content. - `dynamic` boolean: Upstream generates the skill's content and publishes no manifest. - `openapi` McpOpenApiConfig - `document` string: OpenAPI 3.x document as JSON or YAML; accepted on write and never stored or returned. - `document_url` string: URL the document is fetched from; `:sync` fetches it again. - `operations` string[]: Tool names of the operations to expose; empty exposes every operation. - `title` string: `info.title` of the compiled document. - `version` string: `info.version` of the compiled document. - `icons` McpIcon[]: Icons advertised by the upstream server during discovery. - `src` string: Icon URI, including HTTPS URLs and base64 data URIs. - `mime_type` string: Optional MIME type override. - `sizes` string[]: Supported sizes such as "48x48" or "any". - `theme` string: Optional background theme this icon was designed for. - `website_url` string: Website advertised by the upstream server during discovery. - `capabilities` McpServerCapabilities: Capability families advertised by the upstream MCP server during discovery. - `tools` boolean - `resources` boolean - `prompts` boolean - `completions` boolean - `resource_catalog` McpResourceCatalog - `resources` McpResource[] - `uri` string - `name` string - `title` string - `description` string - `mime_type` string - `size` string - `annotations` McpResourceAnnotations: Upstream annotations shared by resource and resource template descriptors. - `audience` string[] - `last_modified` string - `priority` number, double - `icons` McpIcon[] - `src` string: Icon URI, including HTTPS URLs and base64 data URIs. - `mime_type` string: Optional MIME type override. - `sizes` string[]: Supported sizes such as "48x48" or "any". - `theme` string: Optional background theme this icon was designed for. - `meta` object: Resource `_meta` advertised upstream. - `selection_id` string: Opaque selection ID scoped to this saved server and its upstream origin. Omitted on connection probes. - `resource_templates` McpResourceTemplate[] - `uri_template` string - `name` string - `title` string - `description` string - `mime_type` string - `annotations` McpResourceAnnotations: Upstream annotations shared by resource and resource template descriptors. - `audience` string[] - `last_modified` string - `priority` number, double - `icons` McpIcon[] - `src` string: Icon URI, including HTTPS URLs and base64 data URIs. - `mime_type` string: Optional MIME type override. - `sizes` string[]: Supported sizes such as "48x48" or "any". - `theme` string: Optional background theme this icon was designed for. - `meta` object: Resource template `_meta` advertised upstream. - `selection_id` string: Opaque ID for strict selection on a saved server. Omitted on probes and when template variables cannot be matched unambiguously. - `resources_status` 'MCP_DISCOVERY_STATUS_SYNCED' | 'MCP_DISCOVERY_STATUS_UNSUPPORTED' | 'MCP_DISCOVERY_STATUS_FAILED' - `resource_templates_status` 'MCP_DISCOVERY_STATUS_SYNCED' | 'MCP_DISCOVERY_STATUS_UNSUPPORTED' | 'MCP_DISCOVERY_STATUS_FAILED' - `has_more` boolean: Whether further items exist beyond this page. ## Other responses - `401`: Authentication required. See https://docs.orq.ai/reference/errors for the error codes. ## Changes > 1482 revisions in range; 72 not diffed. - **2026-11-13** `efa73c421070`: 3 info - added the new optional `query` request parameter `all_accessible_projects` - added the optional property `data/items/capabilities` to the response with the `200` status - added the optional property `data/items/resource_catalog` to the response with the `200` status - **2026-11-13** `d3a0ce6582b3`: 3 warning - deleted the `query` request parameter `all_accessible_projects` - removed the optional property `data/items/capabilities` from the response with the `200` status - removed the optional property `data/items/resource_catalog` from the response with the `200` status - **2026-11-10** `764b5375e61f`: 3 info - added the new optional `query` request parameter `all_accessible_projects` - added the optional property `data/items/capabilities` to the response with the `200` status - added the optional property `data/items/resource_catalog` to the response with the `200` status - **2026-11-10** `b01d20a20f31`: 3 warning - deleted the `query` request parameter `all_accessible_projects` - removed the optional property `data/items/capabilities` from the response with the `200` status - removed the optional property `data/items/resource_catalog` from the response with the `200` status - **2026-11-10** `9370a6a5fe9d`: 1 info - added the new optional `query` request parameter `all_accessible_projects` [Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/mcp-servers/get.md) --- [API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/45afec4eb040?raw)