Connect a Claude Agent SDK agent to Contro1

Key takeaways

• The agent has its own identity in Contro1 and an Agent key, stored as CONTRO1_API_KEY where it runs.
• It reaches Contro1 as an MCP server: it sees only the Actions it was given in Access, and Contro1 holds the accounts.
• A person approves first whenever your policy says so, in Contro1, Slack or Teams. The agent does not decide that.
• Each run is one trace: its calls through Contro1 and its own work, Bash and files included.

What the agent gets from Contro1

• Who it is: whoami names the agent and the person accountable for it.
• The Actions it was given in Access, and nothing else: reading a mailbox, updating a CRM. Contro1 holds the accounts and makes the call, so the agent never holds a password or a token for them.
• Approvals decided by your policy. When an Action needs a person, Contro1 asks the right one and the call continues after they approve.
• Your organization's skills: the instructions you wrote for how work is done here.
• A way to ask a person before its own work, such as sending a file to a customer.
• A trace of every run, under its own name.

1. Create the agent and give it Actions

In Contro1, open Agents, press New agent, choose "An agent you are building for production" and press Create identity. You are accountable for it.

Then open Access, choose the agent and give it the Actions it needs. It starts with none. Which Actions need a person first is set there and in your policy.

2. Create its Agent key

Open Settings, Agent keys, press Add agent key, choose the agent and name the place it will run, for example "Railway production". Copy the key straight into that place's environment variables as CONTRO1_API_KEY. Make a second key, named for your laptop, to test there.

Where the key goes on Railway, Render, Fly.io, Vercel, AWS and Google Cloud

3. Add Contro1 to the agent's options

Copy this file into your project. It adds the Contro1 MCP server with the agent's key, allows its tools, and sends the agent's own work to Contro1 as a trace. Nothing else in your agent changes.

import os
import secrets

from claude_agent_sdk import ClaudeAgentOptions

CONTRO1_KEY = os.environ["CONTRO1_API_KEY"]
CONTRO1_API = "https://api.contro1.com/api/centcom"


def with_contro1(allowed_tools=(), mcp_servers=None, env=None, **options) -> ClaudeAgentOptions:
    """Your agent's options with Contro1 added. Call it once per run."""
    traceparent = f"00-{secrets.token_hex(16)}-{secrets.token_hex(8)}-01"  # one trace for this run
    return ClaudeAgentOptions(
        **options,
        mcp_servers={
            **(mcp_servers or {}),
            "contro1": {
                "type": "http",
                "url": f"{CONTRO1_API}/mcp",
                "headers": {"Authorization": f"Bearer {CONTRO1_KEY}", "traceparent": traceparent},
            },
        },
        allowed_tools=[*allowed_tools, "mcp__contro1__*"],
        env={
            **(env or {}),
            # The agent's own work (Bash, files, your tools), as a trace in Contro1.
            "TRACEPARENT": traceparent,
            "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
            "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
            "OTEL_TRACES_EXPORTER": "otlp",
            "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL": "http/protobuf",
            "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": f"{CONTRO1_API}/v1/otel/v1/traces",
            "OTEL_EXPORTER_OTLP_TRACES_HEADERS": f"Authorization=Bearer {CONTRO1_KEY}",
        },
    )

4. Use it where you build the options

Pass your existing options through with_contro1, once per run. Each run gets its own trace.

import asyncio

from claude_agent_sdk import ClaudeSDKClient, ResultMessage

from contro1_options import with_contro1


async def run(task: str) -> None:
    options = with_contro1(
        system_prompt="You prepare rebar bar lists from drawings.",  # your options, unchanged
        allowed_tools=["Read"],
    )
    async with ClaudeSDKClient(options=options) as client:
        await client.query(task)
        async for message in client.receive_response():
            if isinstance(message, ResultMessage):
                print(message.result)


asyncio.run(run("Read drawing A-101 and prepare the bar list"))

5. Run it once and check

• Ask the agent "who are you in Contro1?". It answers with its name and its accountable owner, from whoami.
• Activity Logs: the run as one case, with the agent's tool calls and its Actions under one trace.
• Settings, Agent keys: the key shows when it was last used.
• If an Action needed approval, it waited in Live Requests until a person answered, then ran.

Frequently asked questions

Do I install a Contro1 SDK?

No. The Agent SDK connects to the Contro1 MCP itself, and its traces go out over OpenTelemetry. The Contro1 Python SDK is only for calling Contro1 from your own code outside the agent.

Who decides when a person approves?

Your organization, in Contro1: the Action's risk, the grant in Access and your policy. The agent calls the Action; Contro1 asks a person first when the rules say so, and the agent is told to wait for the answer.

What does the trace contain?

Every tool the agent ran, with how long it took and whether it worked, and every Action it called through Contro1. Tool inputs and outputs are left out by default; set OTEL_LOG_TOOL_DETAILS=1 and OTEL_LOG_TOOL_CONTENT=1 in env to include them. Claude Code's tracing is a beta feature of Anthropic's.

Do I need contro1 mcp login or contro1 auth login?

No. Both sign in as a person. The agent uses its own Agent key and nothing else, on your laptop and in production.

I use Claude Managed Agents, not the Agent SDK.

That is Anthropic's hosted product, with its own page: Claude Managed Agents.

Related resources