MCP Servers

​

Use Cases

• Connecting third-party SaaS tools (Slack, Linear, Figma, etc.) to agents without writing custom integrations.
• Exposing internal APIs as callable tools for agents.
• Centralizing MCP server management instead of configuring connections per tool or per agent.
• Sharing a single MCP server across multiple agents and MCP Gateways with controlled tool exposure.

​

How It Works

​

Tool schemas

​

MCP Servers List

• Connection: the server key, with the provider logo when the server comes from the catalog
• Tools: the tool count from the last sync
• Access: which projects can use the server
• Synced at: when the server last synced
• Created by: the workspace member who added it

​

Set Up an MCP Server

• OpenAPI: turns a REST API that publishes an OpenAPI document into tools. See Create from an OpenAPI Specification.
• MCP URL: connects an existing MCP server by its endpoint.
• Catalog: a pre-configured provider. Selecting one fills in the connection URL and the authentication it expects.

1. Fill in the general details.
   • Key (required): lowercase letters, digits, - and _, up to 64 characters. Prefixes tool names in an MCP Gateway and sets display_name. The API also requires default_tool_exposure.
   • Description (optional): a note about what this server provides.
2. Set the connection.
   • Type: HTTP (default) or SSE for streaming-capable servers.
   • URL (required): the endpoint of the upstream MCP server.
3. Configure authentication.
   • None (default): for public servers that require no credentials.
   • Static Headers: send fixed headers with every request. Header values are stored encrypted and never returned by the API. A {{variable}} placeholder keeps a value out of storage: the server stores only the name, and the value is supplied when the server is tested, synced, or a tool is called. Placeholder values are not persisted. A server with template variables cannot be used in an MCP Gateway.
   • OAuth Client Credentials: authenticate with an upstream OAuth 2.0 authorization server using the client credentials grant. Fill in Client ID, Client secret, Token URL and optional Scopes. The secret is stored encrypted and never returned by the API. See How OAuth Client Credentials works. This credential is separate from the OAuth flow MCP clients use to connect to an MCP Gateway.
   • Per-user OAuth: each user connects their own account through the OAuth authorization code flow, and tool calls run with that user’s token. The client settings are optional and sit under Advanced configuration. The option is listed for HTTP and SSE connections. See Per-user OAuth.
   • Enterprise managed (ID-JAG): call the server through an MCP Gateway on behalf of each SSO user. The option is listed when the workspace’s plan includes SSO and the connection is not OpenAPI. Turn on Cross App Access before relying on it: without it, the form warns that tool calls fail until an admin enables it. See Enterprise-managed authorization.
4. Test the connection. Click Test connection to probe the server before saving. For Enterprise managed (ID-JAG), this checks authorization discovery without requesting a user token or listing tools. Other authentication types validate the connection and return discovered tools.
5. Click Create.

​

How OAuth Client Credentials works

• Test connection runs.
• The server syncs its tools.
• A tool is executed through an Agent or an MCP Gateway.

​

Per-user OAuth

• From the server detail page: click Connect account and complete the sign-in at the upstream server. The page then shows Connected and syncs the server’s tools. When a stored connection stops working, the button reads Reconnect account.
• From an Agent: an attached per-user server without a connection shows Connect account in the Agent configuration. An Agent run that reaches the server without a connection fails with Connect your account to this MCP server before using it.
• Through an MCP Gateway: when the calling user has no connection, the gateway asks the MCP client to open a connection link (Connect your account for <server>). Clients without URL elicitation support receive the link in a tool error instead. The link opens a Connect account page listing the server, resource, client, and scopes. Click Continue to authorize or Decline to stop the pending operation, then retry the request from the client. Requests that carry no user identity fail with This server requires a signed-in user connection.

​

Enterprise-managed authorization

​

Troubleshoot enterprise-managed authorization

​

Create from an OpenAPI Specification

1. Select Create in the MCP Servers tab, then Create on the OpenAPI card.
2. Under Specification, pick a Source:
   • URL: the address of the document. Sync fetches it again to pick up changes.
   • Paste or upload: a JSON or YAML document. The document is not stored, so changing the tools later means loading the document again in Settings.
3. Click Load operations and select the operations to expose. Operations that cannot become tools are listed under Skipped operations with the reason.
4. Check Base URL: requests are sent there. It is filled from the first servers entry of the document.
5. Configure Authentication with None, Static Headers (for example an API key header or Authorization: Bearer {{token}}), or OAuth Client Credentials.
6. Click Create. The tools are available right away; there is nothing to sync.

• OpenAPI 3.0, 3.1 and 3.2. Swagger 2.0 documents are rejected.
• JSON request bodies only.
• At most 300 tools per server and a 10 MB document.
• $ref to other files or URLs is not followed; operations that use one are skipped.
• Enterprise managed authentication is not available.
• IDE exports reach OpenAPI servers only through an MCP Gateway.

curl -X POST https://my.orq.ai/v2/mcp-servers \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "petstore",
    "display_name": "petstore",
    "connection": {
      "type": "MCP_CONNECTION_TYPE_OPENAPI",
      "url": "https://petstore3.swagger.io/api/v3"
    },
    "auth": { "type": "MCP_AUTH_TYPE_NONE" },
    "default_tool_exposure": { "mode": "MCP_TOOL_EXPOSURE_MODE_ALL" },
    "openapi": {
      "document_url": "https://petstore3.swagger.io/api/v3/openapi.json",
      "operations": ["getPetById", "findPetsByStatus"]
    }
  }'

​

After Creation

• View discovered tools in the Tools tab: discovered tools sit on the left and the selected tool’s details on the right. Select a tool for its description, arguments, and schema. Filters keeps Read only, Destructive, Idempotent, or Open world tools. Sync state sits on Overview.
• Control tool exposure when the server is linked to an MCP Gateway: select the tool checkboxes on the gateway’s MCP Servers tab (see MCP Gateways). Exposure also accepts a read-only filter in the API. It keeps only the tools the upstream server annotates as read-only (readOnlyHint). The gateway trusts that annotation and does not check what the tool does.
• Test a tool by filling in the arguments and clicking Run tool. The test invokes the tool on the upstream server and shows the response.
• Sync tools adds new tools and keeps missing ones marked MISSING.
• Manage from a menu: row menu Sync tools, Edit, Delete; detail overflow Edit, Share, Duplicate, Delete. Share copies the page link, and Duplicate reuses the connection and tool settings under a new key.
• Configure project access in the Settings tab. Under Access control, pick All projects to share the server with the whole workspace, or Custom and set each project to Enabled or Disabled. An MCP Gateway can only link servers whose project access covers it.

​

Delete a Server

curl -X PATCH https://my.orq.ai/v2/mcp-gateways/<gateway-id> \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_links": [
      {
        "mcp_server_id": "mcp_server_01JQ0K5R8N2ZC7X4M9T3V6HWBE",
        "alias": "weather",
        "tool_exposure": { "mode": "MCP_TOOL_EXPOSURE_MODE_ALL" }
      }
    ]
  }'

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: {
    serverLinks: [
      {
        mcpServerId: "mcp_server_01JQ0K5R8N2ZC7X4M9T3V6HWBE",
        alias: "weather",
        toolExposure: { mode: "MCP_TOOL_EXPOSURE_MODE_ALL" },
      },
    ],
  },
});

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",
    server_links=[
        {
            "mcp_server_id": "mcp_server_01JQ0K5R8N2ZC7X4M9T3V6HWBE",
            "alias": "weather",
            "tool_exposure": {"mode": "MCP_TOOL_EXPOSURE_MODE_ALL"},
        }
    ],
)

curl -X DELETE https://my.orq.ai/v2/mcp-servers/<server-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.mcpServers.delete({
  id: "mcp_server_01JQ0K5R8N2ZC7X4M9T3V6HWBE",
});

import os
from orq_ai_sdk import Orq

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

client.mcp_servers.delete(id="mcp_server_01JQ0K5R8N2ZC7X4M9T3V6HWBE")

​

Monitor Usage

​

Attach to an Agent

​

Attach to a Gateway