Skip to main content

Behavry Integration — Claude Code CLI

Claude Code is the primary supported client for Behavry. The CLI has native support for MCP servers via .claude/mcp.json — no additional tooling required.

Prerequisites​

  • Behavry stack running (make dev or docker compose up)
  • Claude Code installed (npm install -g @anthropic-ai/claude-code)
  • Python 3.11+ with uv available (pip install uv)

Quick Setup​

make setup

This detects Claude Code, provisions a claude-code-local agent with the claude-code-dev role, and merges the MCP server config into ~/.claude/mcp.json — all in one step.

To connect only Claude Code:

cd backend && poetry run python ../demos/setup/create_dev_agent.py --client claude

The applied config looks like:

{
  "mcpServers": {
    "behavry-filesystem": {
      "type": "http",
      "url": "http://localhost:8000/mcp/v1/servers/demo-filesystem/mcp",
      "headers": {
        "Authorization": "Bearer <agent-jwt>"
      }
    }
  }
}

Verify​

  1. Open http://localhost:5173 → Live Activity
  2. Start Claude Code in a project: claude
  3. Ask Claude to list files or read a file
  4. The tool call appears in the Live Activity feed with policy result allow

Token Refresh​

Tokens expire in ~8 hours. Refresh all enrolled editors at once:

make tokens

Windows Notes​

The same steps work on Windows. Use python (not python3) and ensure Docker Desktop for Windows is running. The config file path is automatically resolved to the correct location by mcp_config.py.

Troubleshooting​

"Unauthorized" errors in Claude Code

The JWT has expired. Run python mcp_config.py --apply to refresh.

Tools not appearing

Check that the Behavry stack is running: curl http://localhost:8000/health

Live Activity shows no events

Make sure you're using the configured MCP server name in Claude Code. Run claude --mcp-debug to see which servers are active.