MCP Client Setup

Connect external AI clients to your Qelos tenant as a remote MCP server. Each client uses OAuth: when you connect, the client opens a browser window to your tenant's consent screen — sign in, review the request, and click Accept to grant access.

Before connecting any client, complete the admin prerequisites in Configuration:

• [ ] MCP server enabled
• [ ] Client callback URL on the permitted list
• [ ] Desired tool categories enabled for your role — see Permitted tools

Server URL

Every supported client connects to the same tenant endpoint:

https://<your-tenant-domain>/api/mcp/admin

Replace <your-tenant-domain> with your Qelos tenant host (for example acme.qelos.app). The URL is the same for all clients — only the OAuth callback URI differs per client.

Cursor

Cursor supports remote MCP servers with browser-based OAuth.

1. Permit the callback URL

In Privileged Home → MCP Configuration, add:

cursor://anysphere.cursor-mcp/oauth/callback

This is Cursor's fixed redirect URI. It must match exactly.

2. Add the remote server

Option A — config file (recommended for teams)

Create or edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for a global setup):

{
  "mcpServers": {
    "qelos": {
      "url": "https://<your-tenant-domain>/api/mcp/admin"
    }
  }
}

Option B — Settings UI

1. Open Cursor Settings → Tools & MCP (or Settings → MCP).
2. Click Add server / New MCP server.
3. Choose a remote server and enter the URL above.

3. Authenticate

1. Save the config or add the server in Settings.
2. If the server shows Needs authentication, click Connect (or trigger a Qelos tool from chat).
3. Your browser opens the Qelos consent screen at /mcp/authorize.
4. Sign in with an admin account (when admin-only access is enabled).
5. Review the client name, callback URL, and scopes — click Accept.
6. The browser redirects to cursor://… and Cursor completes the OAuth handshake.

After success, Qelos tools appear under the qelos server in Tools & MCP.

Project vs global config

Use .cursor/mcp.json in a repo to share the server URL with your team. Each developer still completes their own browser consent on first connect.

Claude (Claude.ai, Claude Code, Cowork)

Anthropic clients connect to remote MCP servers through custom connectors. The redirect URI must be on your tenant's permitted list.

1. Permit the callback URL

Add the redirect URI your Claude product uses. The most common pattern:

https://claude.ai/api/mcp/auth_callback

Other URLs on claude.ai or *.anthropic.com are also recognized by the admin form's client hint. Add the exact URI shown in your connector settings — character for character.

Product	Typical setup location
Claude.ai (web)	Settings → Connectors → Add custom connector / remote MCP
Claude Code	MCP or integrations settings — add remote server URL
Cowork	Workspace integrations — add remote MCP connector

UI labels vary by release; look for custom connector, remote MCP, or MCP server URL.

2. Add the Qelos server

1. Open your Claude product's connector or MCP settings.
2. Add a remote MCP or custom connector.
3. Enter the server URL:

https://<your-tenant-domain>/api/mcp/admin

4. Confirm the redirect URI matches what you added in the admin panel.

3. Authenticate

1. Save the connector and start a connection (or use a feature that calls MCP tools).
2. Claude opens a browser window to your tenant consent screen.
3. Sign in and click Accept.
4. The browser redirects to the Claude callback URL; the client stores the session and lists available tools.

Codex / ChatGPT

OpenAI's ChatGPT and Codex surfaces support remote MCP connectors with OAuth.

1. Permit the callback URL

In MCP Configuration, add:

https://chatgpt.com/aip/mcp/oauth/callback

URLs on chatgpt.com or *.openai.com match the admin Codex / ChatGPT hint. Use the exact redirect URI from your connector configuration.

2. Add the Qelos server

1. Open ChatGPT Settings (or your Codex / developer MCP settings).
2. Find Connectors, Apps, or MCP servers — add a remote MCP entry.
3. Enter:

https://<your-tenant-domain>/api/mcp/admin

4. Ensure the OAuth redirect URI in the connector matches your permitted list entry.

3. Authenticate

1. Enable or connect the Qelos MCP server in ChatGPT/Codex.
2. When prompted, complete sign-in in the browser consent screen.
3. Click Accept to grant access.
4. Return to ChatGPT — Qelos tools should be available for the session.

Devin

Devin connects to remote MCP servers for tenant-aware automation.

1. Permit the callback URL

Add Devin's OAuth redirect URI:

https://app.devin.ai/oauth/callback

Other URLs on *.devin.ai are recognized by the admin form. Add the exact URI Devin displays in its MCP setup.

2. Add the Qelos server

1. In Devin, open Settings or Integrations → MCP (or Remote MCP).
2. Add a new remote MCP server.
3. Set the URL to:

https://<your-tenant-domain>/api/mcp/admin

3. Authenticate

1. Save the server configuration and initiate connection.
2. Devin opens a browser to your tenant's /mcp/authorize consent screen.
3. Sign in with an account that passes admin-only and tool checks.
4. Click Accept — Devin receives the OAuth callback and registers Qelos tools.

Other MCP clients

Any client that supports remote MCP with OAuth can connect if:

1. Its redirect URI is added to Permitted callback URLs (HTTPS or custom URI scheme — see Configuration).
2. The client is pointed at https://<your-tenant-domain>/api/mcp/admin.
3. The connecting user completes browser consent.

For custom clients built on @qelos/sdk, see the SDK's MCP auth helpers — that path is for advanced integrations, not standard admin setup.

Troubleshooting

Symptom	Likely cause	Fix
Connection fails immediately; no consent screen	MCP server disabled	Enable Enable MCP server in MCP Configuration and save
OAuth error; redirect rejected	Callback URL not permitted	Add the client's exact redirect URI to permitted callback URLs
Consent shows Administrator access required	Admin-only mode + non-admin user	Sign in as admin/privileged user, or disable admin-only and scope tools
Consent succeeds but no tools in client	No tool categories enabled for user's role	Enable categories in the Tools table; match the user's role
Tool calls fail with permission errors	Role / workspace filters too narrow	Widen Roles, Workspace roles, or Workspace labels for the category — or use an account that matches
Authorization unavailable or expired request	Stale OAuth state	Start again from the client — do not refresh the consent URL manually
Missing authorization state	Broken redirect back to client	Retry from the MCP client; confirm callback URL matches permitted list exactly
Works for admin, not for editors	Admin-only still enabled	Disable admin-only only after scoping tools for non-admin roles
Workspace-scoped tools missing	Workspaces inactive or labels don't match	Enable workspaces in tenant config; adjust wsRoles/wsLabels — see Tools

Check admin first

Most connection failures trace back to Configuration — MCP disabled, missing callback URL, or admin-only blocking the signing-in user. Confirm those before debugging client-side settings.

Next steps

Once connected, try natural-language prompts against your tenant — see Examples & Ideas.

Related documentation

• MCP overview — prerequisites and endpoint URL
• Configuration — enable server, callback URLs, consent flow
• Permitted tools — tool categories and role restrictions
• Permissions & Roles — tenant and workspace roles