# Connect Cursor to Axiom

**Transport:** stdio (Cursor also supports HTTP-SSE; stdio is the v0 path)
**Auth:** local-stdio (Phase 0)
**Status:** Untested — recipe inferred from upstream docs

Cursor is the AI-first code editor by Anysphere. Project-scoped MCP
config lives at `.cursor/mcp.json`; user-global config lives at
`~/.cursor/mcp.json`. Cursor's MCP support went GA in 2025; both stdio
and HTTP-SSE transports are first-class.

## Install prerequisites

- Cursor 0.45 or later (MCP UI in Settings -> Features -> Model Context
  Protocol).
- Same Axiom prerequisites as the Claude Code recipe.

## Configure the connection

Create `.cursor/mcp.json` at your project root (or
`~/.cursor/mcp.json` for user-global):

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

For a worktree without an installed package:

```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"
      }
    }
  }
}
```

Or have Axiom write it for you:

```bash
axi mcp clients --harness cursor --write
```

## Verify

In Cursor, open Settings -> MCP. The `axiom-root` server should show a
green dot and a tool count >= 7. Open the chat panel and use the tools
menu to find `axiom_node__hooks_list`; invoke with no arguments.

Expected response:

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

## Notes

- Cursor's MCP UI surfaces tool side-effect annotations and asks the
  user to allow/deny on first invocation. Tools whose
  `[[extension.mcp.tool]].side_effects = "writes"` will trigger a prompt.
- Cursor supports both `mcpServers` (stdio) and `mcpServers` with a
  `url` field (HTTP-SSE). The HTTP path requires Phase 5 auth in Axiom;
  stick with stdio for now.
- Restart Cursor (or hit "Refresh" in the MCP settings panel) after
  installing/uninstalling an Axiom extension.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Red dot in MCP settings | `command` path not absolute | Use the full path to `axi` or `python3` |
| Tools don't appear in chat | global allow-list disabled | Settings -> MCP -> enable `axiom-root` |
| Schema validation errors | input-schema drift after upgrade | `axi mcp regenerate`, restart Cursor |

## References

- ADR-038 §D7
- Cursor MCP docs: https://docs.cursor.com/context/model-context-protocol

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