# Connect Claude Code to Axiom

**Transport:** stdio
**Auth:** local-stdio (Phase 0)
**Status:** Tested 2026-05-01 against Claude Code 2.1.126

Claude Code is Anthropic's terminal-native agentic harness. It speaks MCP
natively via per-project `.mcp.json` (shared, checked in) or per-user
`~/.claude.json` (private). One block points it at Axiom's root MCP
server; the per-extension entries previously emitted by `axi mcp generate`
are no longer needed.

## Install prerequisites

- Claude Code 2.0 or later. Install per
  https://docs.claude.com/en/docs/claude-code/setup.
- An Axiom checkout where `python -m axiom.extensions.builtins.mcp.server`
  is importable (the standard editable-install workspace works; on the
  worktree, the `PYTHONPATH` env var below substitutes for the install).

## Configure the connection

Drop a `.mcp.json` at the project root where you want Axiom available
(this file is shared — check it in alongside the rest of the project):

```json
{
  "mcpServers": {
    "axiom-root": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["-m", "axiom.extensions.builtins.mcp.server"]
    }
  }
}
```

For private (per-user) wiring instead of project-shared, put the same
block in `~/.claude.json` under `"mcpServers"`.

The `axi` install path is the simpler version — replace `command` with
the absolute path to `axi` and `args` with `["mcp", "serve"]`:

```json
{
  "mcpServers": {
    "axiom-root": {
      "command": "/absolute/path/to/.venv/bin/axi",
      "args": ["mcp", "serve"]
    }
  }
}
```

If you need to run from a worktree where the package is not installed,
add `PYTHONPATH` so the module resolves:

```json
{
  "mcpServers": {
    "axiom-root": {
      "command": "/absolute/path/to/.venv/bin/python3",
      "args": ["-m", "axiom.extensions.builtins.mcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/axiom-checkout/src"
      }
    }
  }
}
```

You can also let Axiom write the file for you:

```bash
axi mcp clients --harness claude-code --write
```

This subsumes the legacy `axi mcp generate` (which still works as an
alias and prints a one-line deprecation notice the first time you use it
per session).

## Verify

From the same directory as `.mcp.json`:

```bash
$ claude mcp list
axiom-root: /absolute/path/to/.venv/bin/python3 -m axiom.extensions.builtins.mcp.server - ✓ Connected
```

Then inside an interactive `claude` session, run `/mcp` to see the
tool list. You should see at least the seven platform primitives:

```
axiom_memory__compose
axiom_memory__retrieve
axiom_memory__list
axiom_federation__node_status
axiom_rag__retrieve
axiom_signals__brief
axiom_node__hooks_list
```

Invoke the universal smoke-test tool:

```
> Use the axiom_node__hooks_list tool with no arguments
```

Expected response shape:

```json
{
  "node": "/Users/<you>/.axiom",
  "hooks_total": 0,
  "events_observed": [],
  "by_event": {}
}
```

(Counts vary with installed extensions — what matters is valid JSON
back.)

## Notes

- Claude Code re-reads `.mcp.json` on session start. If you install or
  uninstall an Axiom extension, restart `claude` (or run `axi mcp regenerate`
  and restart) to pick up the new tool surface.
- Project-scoped `.mcp.json` is checked in; per-user `~/.claude.json` is
  not. Pick based on whether your collaborators should share the same
  Axiom node connection.
- Per ADR-038 D7, the previous per-extension MCP server pattern (one
  entry per extension that ships its own `mcp_server.py`) is replaced by
  the single `axiom-root` entry. Existing Tier-1 client configs from
  `axi mcp generate` continue to work through one minor version, then
  emit a lint warning recommending migration.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `Failed to connect` | wrong `command` path or venv not on PATH | Use absolute path to the venv's `python3` or `axi` binary |
| Empty tool list | server started, but no extensions on PYTHONPATH | Add `env.PYTHONPATH` pointing at `<axiom>/src`, or install Axiom into the venv |
| Surface stale after install | Claude Code caches the tool list per session | `axi mcp regenerate` then `/mcp` again, or restart `claude` |

## References

- ADR-038 §D1, §D7 — root server + adapter recipes
- spec-builtin-mcp-server.md §11 — adapter recipe template
- Claude Code MCP docs: https://docs.claude.com/en/docs/claude-code/mcp

_Copyright (c) 2026 B-Tree Ventures, LLC. Apache-2.0 licensed._
