Connect Claude Code to Contro1

Who this is for

Anthropic's coding agent, on your own computer. For: Claude Code. Acts as: The Claude Code agent itself. Credential: A key in the Contro1 service on the computer.

Claude Code connects as its own agent with one command, which also adds the Contro1 MCP server for company apps; an approval hook then stops risky commands for a person.

Every way 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"
          }
        ]
      }
    ]
  }
}

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. It reports as the Claude Code agent that contro1 connect claude-code connected on this computer, and finds it the same way the MCP server does, so the hook command needs no address. Only a computer with more than one Claude Code connection needs --agent <agent id> in both lines.

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

What you should see: After the next Claude Code 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), and Claude Code shows why: no Claude Code connection here (run contro1 connect claude-code), or several (add the --agent flag it names). Older contro1 versions needed --broker-endpoint here; update contro1 if your settings still have it, then remove it.

Claude Code for an organization

Once Claude Code is connected: choosing which tools wait for a person (Bash, file edits, MCP tools), the reviewer and the reason they see, a computer that is not connected, contro1 ask for a question rather than an approval, and managed settings that make the hook something users cannot turn off.

Claude Code for an organization: approval policy and enforcement

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

When something does not work

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.

Related resources