Cursor and Other Hosts
How do I connect Cursor or another assistant?
Section titled “How do I connect Cursor or another assistant?”Add Controller AI’s hosted MCP connector by URL, then authenticate in the host. Any host with a compatible transport and OAuth can connect. Without a plugin, the assistant reads Controller AI’s skills through guide_list and guide_get.
Set up local Cursor
Section titled “Set up local Cursor”In the app: open Settings → AI assistants → Connect an assistant and select Cursor. Add to Cursor installs the server in one click, or copy the configuration below.
With an assistant: use this connector entry:
{ "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.
For Cloud Agents, add personal MCP through the dropdown at cursor.com/agents. Team admins use Dashboard → Integrations & MCP instead. Cloud Agents fetch guidance through guide_get like any other connector.
Can another host connect?
Section titled “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
Section titled “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 sign in to your Controller AI account, or sign up for one, and check the email before selecting Connect account.
Call account_status with {}. Compare user, account.accessMode, and grantedScopes with the account and access you intended. Only confirmed email addresses are returned, so user.email: null alone does not identify the account. If the call reports that you are not signed in, authenticate the connector again with your own account.
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
Section titled “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.
The server stores no selected workflow, 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.
Check for Support helper without creating anything
Section titled “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 call below returns only your agents.
With an assistant: list the matching agents without creating anything. Call agent_list with:
{ "ownership": "mine", "search": "Support helper" }Report names and IDs, or no matches.
Next: build Support helper, read the skills, or manage assistant access.