Connect Claude Code and Cursor to Contro1

Who this is for

Coding assistants on your own computer. For: Claude Code, Cursor. Acts as: Claude Code: the agent itself. Cursor: you. Credential: Claude Code: a key in the Contro1 service. Cursor: your MCP sign-in.

Claude Code connects as its own agent with one command, which also adds the Contro1 MCP server; an approval hook then stops risky commands for a person. Cursor has no connect command: it runs the Contro1 MCP server locally and acts as you.

All four ways to connect an agent

Connect Claude Code

Claude Code on this computer becomes one Contro1 agent, named "Claude Code on <computer name>", with you as its accountable owner. A Contro1 service on the computer holds its key, which cannot be exported, so Claude Code never holds a credential. connect also registers the Contro1 MCP server with Claude Code for every folder.

Connect Claude Code, step 1: Install the Contro1 CLI

Once per computer. The installer downloads the contro1 program from its official GitHub releases. You can read it first at https://contro1.com/install.sh (PowerShell: https://contro1.com/install.ps1).

curl -fsSL https://contro1.com/install.sh | sh
contro1 --version

irm https://contro1.com/install.ps1 | iex
contro1 --version

What you should see: The installer ends with "Installed contro1 to <folder>", and contro1 --version prints "contro1 version 0.2.29" or later. On Windows, if contro1 is not found, open a new terminal: the installer added it to your PATH.

Connect Claude Code, step 2: Sign in to Contro1 on this computer

A browser opens on a Contro1 approval page. Approve it with your Contro1 account.

contro1 auth login

What you should see: "Logged in as you@company.com (Org: <your organization>)".

Connect Claude Code, step 3: Connect Claude Code

connect lists every change before it makes any: the local Contro1 service, the settings file ~/.contro1/claude-code.env that the approval hook reads, and the Contro1 MCP server for Claude Code at user scope, so it works in every folder.

At "Continue? [y/N]" type y. It then asks once for administrator approval, to register the agent key with the Contro1 service: a Windows administrator prompt, or your password on macOS and Linux.

contro1 connect claude-code

What you should see: The list includes "Register the Contro1 MCP server with Claude Code, for every folder: claude mcp add --scope user contro1 -- contro1 mcp serve --agent claude-code@<id>", then "Continue? [y/N]" and the administrator prompt.

Connect Claude Code, step 4: Approve the agent as its owner

connect prints an approval link and waits up to 11 minutes. Open it and approve. A computer that is already connected skips this step: Contro1 reuses its agent.

What you should see: "Approve at https://contro1.com/... Code: ABCD-EFGH", then "Approved.", "Configuring claude-code..." and "Checking each agent...".

Connect Claude Code, step 5: Let connect add the MCP server, then restart Claude Code

Nothing to type: this is the end of the same run. connect runs claude mcp add itself, then calls the server through the agent's own endpoint. A Claude Code window that was already open does not see the new server until you restart it.

claude mcp get contro1

What you should see: "Registered the Contro1 MCP server with Claude Code. New sessions load it; a session already open needs a restart." and "MCP connected: N actions available." claude mcp get contro1 shows "Scope: User config" and "Args: mcp serve --agent claude-code@<id>". In a restarted Claude Code, /mcp lists contro1 as connected.

Connect Claude Code, step 6: Add the approval hook for risky commands

connect cannot install this, so until it is there the end of connect says "But it is not working end to end yet" and names it. The hook asks a person in Contro1 before Claude Code runs a matching command, and needs no key: on a connected computer it finds the connection by itself.

Install it, then add it to ~/.claude/settings.json, merged with what is already there.

npm install -g @contro1/claude-code

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "centcom-claude-code",
            "timeout": 910,
            "statusMessage": "Waiting for approval in Contro1"
          }
        ]
      }
    ]
  },
  "env": {
    "CENTCOM_REQUIRED_ROLE": "cto"
  }
}

What you should see: Run contro1 connect claude-code again. The "Approvals for risky commands" line is gone, and it ends with "Try it: ask Claude Code to run a command that needs approval."

Connect Claude Code, step 7: Check every line

doctor checks the Contro1 service, the agent's mapping and private endpoint, an approval round trip (a preview, nothing is created), the MCP server entry and a live MCP call.

contro1 doctor claude-code

What you should see: The first line is "Contro1 doctor: claude-code is connected", and every check under it starts with ✓. A line marked ! or ✗ is followed by "Next (you): <command>". Run that command.

Connect Claude Code, step 8: Try it

In a test project whose package.json has "deploy": "echo deployed", ask Claude Code to run npm run deploy.

What you should see: Claude Code waits with "Waiting for approval in Contro1", and a request appears in Contro1. Approve it and the command runs. Reject it and Claude Code is told it was denied.

Connect Claude Code, step 9: Optional: report every tool call

contro1 activity hook reports each Claude Code tool call to Contro1 from outside the model, one session per trace. On a connected computer it needs the agent's local endpoint, which contro1 mcp endpoint prints. Put that value in the hook command with --broker-endpoint.

contro1 mcp endpoint

{
  "hooks": {
    "PreToolUse":  [{ "matcher": "*", "hooks": [{ "type": "command", "command": "contro1 activity hook --fail-closed --broker-endpoint <endpoint>" }] }],
    "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "contro1 activity hook --broker-endpoint <endpoint>" }] }]
  }
}

What you should see: contro1 mcp endpoint prints one line such as unix:///... or npipe:////./pipe/.... After the next session, each tool call appears in the agent's traces in Contro1. With --fail-closed, a tool whose start could not be recorded is blocked (exit code 2).

Connect Cursor

There is no contro1 connect cursor. Cursor gets the Contro1 MCP server by running contro1 mcp serve as a local server, signed in as you. It can then list and run the Actions you may use, every call checked by Contro1 and recorded as yours.

Adding the remote address https://api.contro1.com/api/centcom/mcp directly in Cursor does not work today. Cursor's sign-in returns to a cursor:// address, which Contro1 refuses because the code would only reach the computer that opened the link. Use the local server below.

Connect Cursor, step 1: Install the Contro1 CLI

Once per computer. The installer downloads the contro1 program from its official GitHub releases. You can read it first at https://contro1.com/install.sh (PowerShell: https://contro1.com/install.ps1).

curl -fsSL https://contro1.com/install.sh | sh
contro1 --version

irm https://contro1.com/install.ps1 | iex
contro1 --version

What you should see: The installer ends with "Installed contro1 to <folder>", and contro1 --version prints "contro1 version 0.2.29" or later. On Windows, if contro1 is not found, open a new terminal: the installer added it to your PATH.

Connect Cursor, step 2: Sign the MCP connection in as you

This gives the local Contro1 MCP server a sign-in of its own, separate from contro1 auth login. --execute asks for permission to run Actions; without it the connection can only read and preview.

It shows a code and opens the approval page. You can approve on this computer or on any other device, such as your phone. On the page, check that "Run Actions as you" is ticked, then press Approve.

contro1 mcp login --execute

What you should see: "To connect, open this address on any device and approve: https://contro1.com/connect-app and enter the code: ABCD-EFGH". After you approve: "MCP connected for profile default (mcp:whoami, ..., mcp:actions:execute)." and "See or disconnect it anytime in Contro1: Settings > Connected apps."

Connect Cursor, step 3: Add Contro1 to Cursor

Put this in ~/.cursor/mcp.json for every project, or in .cursor/mcp.json inside one project. Merge it with any servers already there.

{
  "mcpServers": {
    "contro1": {
      "command": "contro1",
      "args": ["mcp", "serve"]
    }
  }
}

What you should see: In Cursor Settings, the MCP section (Tools & MCP in recent versions) lists contro1 as enabled, with its tools.

Connect Cursor, step 4: Try it

In Cursor's chat, ask: "Who am I in Contro1?"

What you should see: Cursor calls the whoami tool, which names you and your organization. Ask it to list the Actions it can use, and it calls list_actions.

Give it something to do

A connected agent starts with nothing. It can ask people for approval and report what it did. To use an application such as Gmail, two things happen in Contro1:

• Apps: an administrator turns the application on for the organization and chooses which of its Actions are allowed. That alone gives no agent a tool.
• Access: a person opens the agent, connects the account it should use (a shared team account, or their own), ticks the Actions it may run, and presses Save. People can do this for their own agents, within what the organization allows.
• A personal account, such as your own mailbox, is always used on your behalf. When you are the agent's owner and give it your own account in Access, that is recorded as you letting it act for you. Anybody else whose account it should use turns that on for the agent in Access themselves.
• The agent's page shows a "Get it working" card with three steps: Connected to Contro1, Can do something, Did something. It always shows the next one to do, and it disappears once all three are done.

Action Gateway: apps and access

Frequently asked questions

Does Claude Code need an API key for Contro1?

No. After contro1 connect claude-code the key stays in the Contro1 service on the computer. The MCP server and the approval hook both reach Contro1 through the agent's private local endpoint.

Is there a contro1 connect for Cursor?

No. Cursor runs contro1 mcp serve as a local MCP server, signed in with contro1 mcp login --execute, and acts as you. It is not registered as its own agent with a key in the Contro1 service.

Why can I not add the Contro1 URL directly in Cursor?

Cursor's sign-in sends the authorization code to a cursor:// address on the same computer. Contro1 refuses loopback and private-scheme addresses, because the person approving is often on a different device. The local server signs in with a code instead, which works from any device.

Related resources