# Connect Claude.ai to Axiom

**Transport:** HTTP/SSE (remote MCP connectors only)
**Auth:** token + principal — Phase 5 work in Axiom; not available today
**Status:** Pending Axiom Phase 5 — recipe documents what's possible now and what unblocks at Phase 5

Claude.ai (the web UI / Claude Desktop) connects to MCP servers via the
"Connectors" path. Connectors are remote HTTP/SSE-only — there is no
local-stdio mode equivalent to Claude Code's `.mcp.json`. That means
Claude.ai needs Axiom's HTTP transport, which ships in Phase 5 per
[ADR-038 D6](../../adrs/adr-038-builtin-mcp-server.md).

## What's possible today

Nothing direct. `axi mcp serve --http` returns a `NotImplementedError`
with a "Phase 5 — see ADR-038 D6" message. There is no local-only path
that Claude.ai can reach.

What you *can* do today: use Claude Code (which speaks stdio) for the
same model, via the [claude-code.md](claude-code.md) recipe. Claude Code
is the production-ready Anthropic harness for Axiom integration during
Phase 0–4.

## What unblocks at Phase 5

Phase 5 lands three things that together make this recipe live:

1. **HTTP/SSE transport on the Axiom side.**
   `axi mcp serve --http --port <n> --auth token` starts an HTTP-SSE MCP
   server. The transport is the standard MCP-over-SSE protocol that
   Claude.ai's connector path expects.

2. **Token-based auth.** `axi mcp tokens add claude-ai` generates a
   pre-shared bearer token stored in `~/.axiom/mcp/tokens.json`. The
   token is the only credential the connector needs.

3. **Reachable URL.** The Axiom node must be addressable from Anthropic's
   connector infrastructure — typically via a tunnel
   (Cloudflare Tunnel, Tailscale Funnel, ngrok) or a public host. For
   classroom / institutional deployments, a stable HTTPS endpoint with
   a real cert.

## Phase 5 recipe (forward-compatible draft)

Once Phase 5 ships, the recipe will look like:

### Install prerequisites

- Claude.ai with Connectors access (Plus / Team / Enterprise as of 2026-Q2).
- Axiom 0.X+ (whichever release lands Phase 5; tracked in ADR-038
  Phasing table).

### Configure the connection

On the Axiom host:

```bash
axi mcp tokens add claude-ai-personal
# prints: token = a1b2c3d4...  store this safely; revoke with `axi mcp tokens revoke <name>`

axi mcp serve --http --port 8443 --auth token
# serves at https://<your-host>:8443/mcp
```

In Claude.ai: Settings -> Connectors -> Add connector -> "Custom MCP
server":

| Field | Value |
|---|---|
| Name | `axiom-root` |
| Server URL | `https://<your-host>:8443/mcp` |
| Authentication | Bearer token |
| Token | `<paste from above>` |

### Verify

Open a Claude.ai conversation with the connector enabled. Ask:

```
Use axiom_node__hooks_list with no arguments and show me the JSON
result.
```

Expected:

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

## Architecture (Phase 5)

```mermaid
flowchart TD
  classDef cloud fill:#1f2937,color:#f9fafb,stroke:#9ca3af
  classDef edge fill:#7c2d12,color:#fed7aa,stroke:#fed7aa
  classDef tunnel fill:#1e3a8a,color:#dbeafe,stroke:#dbeafe
  classDef axiom fill:#365314,color:#d9f99d,stroke:#d9f99d

  CA[Claude.ai web]:::cloud
  ANT[Anthropic connector infra]:::cloud
  TUN[Cloudflare Tunnel<br/>or Tailscale Funnel]:::tunnel
  HOST[Your Axiom host]:::edge
  AX[axi mcp serve --http --auth token]:::axiom
  STORE[(~/.axiom/mcp/tokens.json)]:::axiom

  CA --> ANT
  ANT -.HTTPS + Bearer.-> TUN
  TUN --> HOST
  HOST --> AX
  AX --> STORE
```

## Notes

- Token auth is a v0 mechanism. Principal-binding (`auth = "principal"`)
  per `feedback_principal_naming` is the longer-term goal — each
  connector identity maps to a Matrix-style `@claude-ai-personal:axiom`
  principal so per-tool `allowed_principals` works correctly.
- The `auth = "local_stdio"` mode explicitly refuses HTTP transport
  (the spec calls this out at §5.2) — there is no "open the door"
  shortcut.
- For institutional deployments where the Axiom node lives behind a
  firewall, a tunnel or jump host is required; Anthropic's infra needs
  to be able to reach the URL.

## Phase tracking

- Phase 5 acceptance per ADR-038: "Claude.ai connector + ChatGPT
  Desktop can connect to a remote Axiom node behind token auth."
- This recipe will be updated to "Tested" status the first time we
  successfully ship Phase 5 + run the verify step end-to-end.

## References

- ADR-038 §D6 (auth staging), §D7
- spec-builtin-mcp-server.md §5.2 (HTTP entry point)
- Anthropic connectors docs: https://support.claude.com/en/articles/11175166

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