Setup

Connect the Orchly MCP server to your AI client. Most clients just need the server URL; they handle the sign-in for you.

Before you start

Whichever client you use, the server URL is the same:

https://app.orchly.ai/api/mcp

On first connect, the client opens an Orchly consent page in your browser. Sign in and approve access, and the session persists. If your client doesn't support OAuth, use an API key instead.

Claude

In Claude Desktop or Claude on the web, open Settings → Connectors (or Developer settings), add a custom connector, and paste the server URL. Claude walks you through the OAuth sign-in. In Claude Code, add it to your MCP config:

{
  "mcpServers": {
    "orchly": {
      "url": "https://app.orchly.ai/api/mcp"
    }
  }
}

Cursor

Open Settings → MCP and add a new server, or edit your mcp.json directly with the config above. Cursor opens the OAuth flow on connect.

VS Code

With GitHub Copilot's agent mode, add the server in your MCP settings (.vscode/mcp.json or the global MCP config) using the same URL and config shape.

Windsurf

Open the MCP settings and add a server with the URL above, or paste the config into your Windsurf MCP file.

Using an API key

For headless clients, CI, or any tool without OAuth, authenticate with an Orchly API key instead. Create one in your Orchly settings, then attach it as an Authorization header on the MCP connection:

{
  "mcpServers": {
    "orchly": {
      "url": "https://app.orchly.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer obk_live_xxx"
      }
    }
  }
}

It's the same key the REST API uses, and it respects the same workspace and permissions.

Troubleshooting

• The client can't connect. Confirm the URL is exactly https://app.orchly.ai/api/mcp and that your client supports the Streamable HTTP transport.
• Sign-in doesn't appear. Some clients only support API-key auth. Use the API-key config above.
• It connects but can't see your data. Make sure you authorized the workspace you mean to query. Ask the assistant to "list my workspaces" to check.

Next, see use cases for what to ask, or the tools reference.