Skip to main content

Behavry Integration — Claude Code CLI

Claude Code is the primary supported client for Behavry. It speaks MCP over Streamable HTTP natively, so connecting it is a single claude mcp add command — no bridge or extra tooling.

Every agent connects through Behavry's unified MCP gateway at /mcp/v1. You authenticate with the agent's client credentials (a client_id / client_secret pair), sent as an HTTP Basic header. Behavry resolves the agent's identity, applies policy, and routes to whichever target MCP servers that agent is entitled to.

Prerequisites​

  • A running Behavry instance (your control-plane URL, e.g. https://app.behavry.ai, or http://localhost:8000 for a local stack)
  • Claude Code installed (npm install -g @anthropic-ai/claude-code)
  • An enrolled agent (see below) — this is what gives you the client_id / client_secret

1. Enroll the agent​

In the dashboard, go to Agents → Enroll Agent, choose Claude Code as the client, and give the agent a name. Behavry provisions the agent and shows you a ready-to-paste command with the credentials already filled in.

Copy that command — it looks like this:

claude mcp remove behavry --scope user 2>/dev/null; \
claude mcp add --transport http --scope user behavry \
  https://<your-behavry-host>/mcp/v1 \
  --header "Authorization: Basic <base64(client_id:client_secret)>"

The leading remove makes re-running idempotent (it's a no-op the first time). Run it in any terminal, then restart Claude Code.

tip

The Authorization value is Basic followed by base64 of client_id:client_secret. The dashboard computes it for you — you should never have to construct it by hand.

2. What it writes​

The command registers a single MCP server named behavry pointed at the unified gateway. The equivalent JSON (if you prefer to edit ~/.claude/settings.json by hand) is:

{
  "mcpServers": {
    "behavry": {
      "url": "https://<your-behavry-host>/mcp/v1",
      "headers": {
        "Authorization": "Basic <base64(client_id:client_secret)>"
      }
    }
  }
}

Note: the gateway is a single endpoint (/mcp/v1) — you do not point at per-server paths. Behavry decides which target servers the agent can reach based on its policy.

Verify​

  1. Open the dashboard → Live Activity (or Audit → Live Stream)
  2. Start Claude Code in a project: claude
  3. Ask Claude to list or read files
  4. The tool call appears in the live feed with a policy result (allow / deny / escalate)

Troubleshooting​

401 Unauthorized The credentials are wrong or the agent was revoked. Re-enroll from Agents → Enroll Agent and paste the fresh command. (Behavry client credentials don't expire on a timer the way the old enrollment JWTs did, but a revoked or rotated agent will 401.)

Tools not appearing Confirm the server registered: claude mcp list should show behavry. Then check the stack is reachable: curl https://<your-behavry-host>/health.

Live Activity shows no events Run claude --mcp-debug to confirm Claude Code is talking to the behavry server, and verify the URL ends in /mcp/v1 (not a per-server path).

Windows Notes​

The same claude mcp add command works on Windows (PowerShell or CMD). The 2>/dev/null idempotence prefix is POSIX-only — on Windows just run the claude mcp add line on its own; if the server already exists, run claude mcp remove behavry --scope user first.