Cursor and Other Hosts

How do I connect Cursor or another assistant?

For local Cursor, setup installs Controller AI skills and prints MCP configuration. Paste that configuration into Cursor, then authenticate there. Other hosts need a compatible transport and OAuth, or terminal access to the CLI. The CLI examples below are account-scoped and assume no workflow pin.

Set up local Cursor

In the app: open Connect and find Set up your coding agent. Select the copy icon beside the prompt, then paste the prompt into Cursor.

With an assistant: install the CLI, then inspect the plan without changing anything:

cai agent setup --client cursor --status --json

After reviewing the plan, apply it:

cai agent setup --client cursor --yes --json

Without an interactive terminal, a plan with pending actions requires --yes. Otherwise setup makes no changes and returns error.code: SETUP_CONFIRMATION_REQUIRED, with “Setup was not changed. Rerun with —yes to approve the printed plan.” Browser authorization still requires you.

If the CLI credential is missing or was rejected, authorization runs before skill installation. A later failure leaves earlier changes in place. In a multi-client setup, a thrown error also stops later clients. A same-name skill that setup does not manage stops installation with UNMANAGED_SKILL_EXISTS. Move the conflicting folder, then inspect status before you retry.

Setup prints this configuration without writing Cursor’s file:

{
  "mcpServers": {
    "controllerai": {
      "type": "http",
      "url": "https://mcp.getcontroller.ai/mcp"
    }
  }
}

Merge that entry into mcpServers in ~/.cursor/mcp.json for the global scope, or .cursor/mcp.json for the project. Enable it under Customize, then complete OAuth. Inspect Output → MCP Logs for connection errors. Cursor MCP controls.

The default global skill scope writes to ~/.cursor/skills. Adding --skills-scope project writes to .agents/skills and checks the project’s MCP configuration. If Cursor is not detected, place the configuration manually, then install the skills:

cai skills install --target cursor --json

Setup recognizes only mcpServers.controllerai with type: "http" and the exact URL above. A different key, a missing type, a query string, or /readonly all report unconfigured. Its current result checks configuration and skills, not OAuth.

For Cloud Agents, add personal MCP through the dropdown at cursor.com/agents. Team admins use Dashboard → Integrations & MCP instead. To copy ~/.cursor/skills, enable Settings → Agents → Sync Skills for Cloud Agents. Project skills and ~/.agents/skills are excluded from skill sync.

Can another host connect?

Requirement	Controller AI accepts	Host check
Transport	Stateless Streamable HTTP over POST	No server-initiated SSE/session stream; GET and DELETE return 405, Allow: POST.
Protocol	2026-07-28, 2025-11-25, 2025-06-18	Another advertised version returns Unsupported MCP protocol version.
OAuth	Metadata discovery, authorization-code and refresh-token grants, S256 PKCE, exact MCP resource	Configure https://mcp.getcontroller.ai/mcp; support HTTPS redirects or loopback HTTP.

Dynamic client registration accepts 1–20 unique redirect URIs, and rejects custom URI schemes. Client-ID metadata documents work only from configured allowlisted origins, and they must advertise token authentication method none. The default origins are https://chatgpt.com and https://claude.ai. A client that is neither listed nor registered returns Unknown OAuth client.

Verify the MCP account and access

At consent, Allow full access requires a requested controller:full. Continue read-only requires a requested controller:read. An omitted scope defaults to full. If the choice you need is absent, change the host’s requested scope. Then choose My Controller account → Continue or Separate agent account → Use agent account. For your own account, check the email before selecting Connect account. Choosing a separate account again can continue the same identity.

Call account_status with {}. Compare user, account.kind, account.accessMode, and grantedScopes with the account and access you intended. The kinds are member, agent, or claimed. Only confirmed, real email addresses are returned, so user.email: null alone does not identify the account.

account.kind: agent means an unclaimed separate account, created without your email or password, and it returns user.email: null. Inspect its reported usage allowance. Then offer optional claiming. Call account_claim_start with email, then account_claim_verify with the six-digit code. Both require controller:full on /mcp. Claiming removes the unverified cap and enables email recovery. Rerun account_status to verify claimed.

Writes require controller:full on /mcp. If you want read-only access enforced, separately authorize https://mcp.getcontroller.ai/mcp/readonly. It blocks writes regardless of the reported scope or account.accessMode. Switching between these routes requires fresh OAuth, because tokens bind to their resource. To enable writes, reconnect to /mcp with full scope requested, then select Allow full access.

https://mcp.getcontroller.ai/mcp?toolsets=read filters discovery only. Account and guide tools remain visible, including the account tools that require full access.

Fetch guidance without local files

Call guide_list with {}, then guide_get with {"name":"controllerai-start"}. It returns bundled instructions and reference contents without installing files.

MCP stores no workflow pin, so pass workflowId on scoped calls. Supply instructions and file content inline. For example, support-policy.md needs its policy text, not a filesystem path.

Use the CLI when MCP is unavailable

For terminal-capable assistants, connect the CLI separately, then read back its authorization and skill state:

cai connect --target agents --json
cai auth status --json
cai skills status --target agents --json

connect updates ~/.agents/skills before authentication, so a failed authorization still leaves skill changes. Inspect auth and skill status before you retry. This authorizes the CLI, not host MCP.

Check for Support helper without creating anything

In the app: open Agents. You have no agents yet is a valid empty inventory. Otherwise search Support helper. The default All agents includes shared agents, while the query below returns only your agents.

With an assistant: list the matching agents without creating anything:

cai agent list --ownership mine --search "Support helper" --json

For MCP, call agent_list with {"ownership":"mine","search":"Support helper"}. Report names and IDs, or no matches.

Next: build Support helper, update skills, or manage assistant access.