# MCP harness adapter recipes for Axiom

Axiom's built-in root MCP server (per [ADR-038](../../adrs/adr-038-builtin-mcp-server.md) and [spec-builtin-mcp-server.md](../../specs/spec-builtin-mcp-server.md)) exposes every installed extension's capabilities — plus seven platform primitives — through the Model Context Protocol standard. One server per node, one well-known surface for every peer harness. Below is a connect-in-five-minutes recipe for each notable harness in the agentic-platform space.

## What you get

A single stdio MCP server (`python -m axiom.extensions.builtins.mcp.server`) exposes the whole node:

- **7 platform primitives** — always present, regardless of installed extensions:
  `axiom_memory__compose`, `axiom_memory__retrieve`, `axiom_memory__list`,
  `axiom_federation__node_status`, `axiom_rag__retrieve`,
  `axiom_signals__brief`, `axiom_node__hooks_list`.
- **N extension contributions** — every AEOS extension that opts in via
  `[extension.mcp]` adds its tools, resources, and prompts under a
  per-extension prefix.

Inspect the live surface from the CLI at any time:

```bash
axi mcp status        # tool / resource / prompt counts + content hash
axi mcp list-tools    # one line per tool with source extension
axi mcp inspect <tool>
```

## How the harnesses split

```mermaid
flowchart TD
  classDef root fill:#7c2d12,color:#fed7aa,stroke:#fed7aa
  classDef tier1 fill:#1f2937,color:#f9fafb,stroke:#9ca3af
  classDef tier2 fill:#1e3a8a,color:#dbeafe,stroke:#dbeafe
  classDef tier3 fill:#365314,color:#d9f99d,stroke:#d9f99d
  classDef tier4 fill:#3f0d3f,color:#f5d0fe,stroke:#f5d0fe

  Root[axiom-root MCP server<br/>stdio + HTTP-SSE]:::root

  subgraph T1[Tier 1 - MCP-native, stdio, ready today]
    CC[Claude Code]:::tier1
    CR[Cursor]:::tier1
    GO[Goose]:::tier1
    CT[ChatGPT Desktop]:::tier1
    CD[Continue.dev]:::tier1
    CL[Cline]:::tier1
    WS[Windsurf]:::tier1
    AI[Aider]:::tier1
    CY[Cody]:::tier1
    OI[Open Interpreter]:::tier1
  end

  subgraph T2[Tier 2 - MCP-native, HTTP/SSE, Phase 5 auth]
    CA[Claude.ai connector]:::tier2
  end

  subgraph T3[Tier 3 - framework adapters]
    LC[LangChain]:::tier3
    CE[CrewAI]:::tier3
    AG[AutoGen]:::tier3
    MA[Mastra]:::tier3
    CX[Codex]:::tier3
  end

  subgraph T4[Tier 4 - bridge or upstream-pending]
    HE[Hermes]:::tier4
  end

  CC --> Root
  CR --> Root
  GO --> Root
  CT --> Root
  CD --> Root
  CL --> Root
  WS --> Root
  AI --> Root
  CY --> Root
  OI --> Root
  CA -.HTTP/SSE.-> Root
  LC --> Root
  CE --> Root
  AG --> Root
  MA --> Root
  CX --> Root
  HE -.bridge.-> Root

  style T1 fill:#0f172a,color:#e2e8f0,stroke:#9ca3af
  style T2 fill:#172554,color:#dbeafe,stroke:#dbeafe
  style T3 fill:#1a2e05,color:#d9f99d,stroke:#d9f99d
  style T4 fill:#1e0a1e,color:#f5d0fe,stroke:#f5d0fe
```

## Harness inventory

| Harness | Tier | Transport | Recipe | Upstream MCP docs |
|---|---|---|---|---|
| Claude Code | 1 | stdio | [claude-code.md](claude-code.md) | https://docs.claude.com/en/docs/claude-code/mcp |
| Cursor | 1 | stdio + HTTP | [cursor.md](cursor.md) | https://docs.cursor.com/context/model-context-protocol |
| Goose (Block) | 1 | stdio + HTTP | [goose.md](goose.md) | https://block.github.io/goose/docs/getting-started/using-extensions |
| ChatGPT Desktop | 1 | stdio (local), HTTP (connectors GA) | [chatgpt-desktop.md](chatgpt-desktop.md) | https://platform.openai.com/docs/mcp |
| Continue.dev | 1 | stdio + HTTP | [continue-dev.md](continue-dev.md) | https://docs.continue.dev/customize/deep-dives/mcp |
| Cline | 1 | stdio + HTTP | [cline.md](cline.md) | https://docs.cline.bot/mcp/configuring-mcp-servers |
| Windsurf | 1 | stdio + HTTP | [windsurf.md](windsurf.md) | https://docs.windsurf.com/windsurf/cascade/mcp |
| Aider | 1 | stdio (experimental) | [aider.md](aider.md) | https://aider.chat (MCP support tracked upstream) |
| Cody (Sourcegraph) | 1 | stdio (OpenCtx bridge) | [cody.md](cody.md) | https://sourcegraph.com/docs/cody/capabilities/openctx |
| Open Interpreter | 1 | stdio (via shell bridge) | [open-interpreter.md](open-interpreter.md) | https://docs.openinterpreter.com |
| Claude.ai connector | 2 | HTTP/SSE | [claude-ai.md](claude-ai.md) | https://support.claude.com/en/articles/11175166 |
| LangChain | 3 | stdio + HTTP (`langchain-mcp-adapters`) | [langchain.md](langchain.md) | https://github.com/langchain-ai/langchain-mcp-adapters |
| CrewAI | 3 | stdio + HTTP (`MCPServerAdapter`) | [crewai.md](crewai.md) | https://docs.crewai.com/en/mcp/overview |
| AutoGen (Microsoft) | 3 | stdio + HTTP (`autogen-ext[mcp]`) | [autogen.md](autogen.md) | https://microsoft.github.io/autogen |
| Mastra | 3 | stdio + HTTP (`@mastra/mcp`) | [mastra.md](mastra.md) | https://mastra.ai/en/docs/tools-mcp/mcp-overview |
| Codex (OpenAI CLI) | 3 | stdio | [codex.md](codex.md) | https://github.com/openai/codex |
| Hermes (Nous Research) | 4 | bridge / upstream-pending | [hermes.md](hermes.md) | https://nousresearch.com (no first-party MCP client) |

## How to verify your connection works

Every recipe ends with this same verify step. The tool used —
`axiom_node__hooks_list` — is a zero-arg, always-present platform primitive,
so it works regardless of which extensions you have installed.

Inside your harness (or via a one-shot programmatic call), invoke:

```
axiom_node__hooks_list()
```

Expected response shape (from the live `axi mcp inspect axiom_node__hooks_list` schema):

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

If `hooks_total > 0`, you'll see one entry per registered hook keyed by event
name. The exact counts depend on what extensions you've installed — what
matters is that the call succeeds and returns valid JSON.

You can also run `axiom_node__hooks_list` from the CLI for a baseline:

```bash
$ axi mcp inspect axiom_node__hooks_list
name:        axiom_node__hooks_list
source:      platform
description: List hooks installed on this node (diagnostics).
input_schema:
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

If your harness's `list_tools` returns at least the seven platform primitives
above, the connection is live. If `axiom_node__hooks_list` returns valid JSON,
the dispatch loop is healthy.

## Recipe template

Every per-harness file follows this shape:

```markdown
# Connect <Harness> to Axiom

**Transport:** stdio / HTTP-SSE / both
**Auth:** local-stdio (Phase 0) / token (Phase 5) / principal (Phase 5)
**Status:** Tested / Untested / Pending upstream

## Install prerequisites
<harness-specific install steps>

## Configure the connection
<config snippet — TOML, JSON, or whatever the harness uses, with the
exact path Axiom's root MCP server is launched from>

## Verify
<the universal `axiom_node__hooks_list` call with expected output shape>

## Notes
<harness-specific quirks, version requirements, gotchas>
```

## Status legend

- **Tested 2026-05-01** — recipe was exercised end-to-end against the
  named upstream version on this date.
- **Untested — recipe inferred from upstream docs** — written from the
  harness's published MCP docs, but not exercised in this session
  (usually because installing the harness was out of scope).
- **Pending upstream** — the harness does not yet ship a usable MCP
  client; recipe documents the shell-bridge fallback and what would
  unblock first-class support.

## Auth posture today vs Phase 5

Every Tier-1 recipe uses **stdio + local-only**. There is no token, no
principal binding, no network exposure. The harness spawns the Axiom MCP
server as a subprocess; whatever can spawn the subprocess gets full
access. This matches every other peer harness's MCP local-install
pattern (Claude Code, Cursor, Goose, etc.).

HTTP/SSE — required for Claude.ai connectors and any "shared node"
deployment — ships with Phase 5 auth (`auth = "token"` and
`auth = "principal"`) per ADR-038 D6. Until then, `axi mcp serve --http`
returns a `NotImplementedError` with a clear "Phase 5" message. Recipes
for HTTP-required harnesses note this explicitly and document what
unblocks at Phase 5.

## Architecture reference

For the full surface contract, drift detection, and aggregation algorithm,
see [spec-builtin-mcp-server.md](../../specs/spec-builtin-mcp-server.md).
For the design rationale, see [ADR-038](../../adrs/adr-038-builtin-mcp-server.md).

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