# The Aura MCP Server

*One server, 29+ tools, every AI agent in your stack.*

## Overview

Aura ships with a first-class **Model Context Protocol (MCP) server** named `aura-vcs`. MCP is the open protocol Anthropic introduced for exposing tools to AI agents. Once Aura's MCP server is enabled, any MCP-aware client — Claude Code, Claude Desktop, Cursor, Zed, Windsurf, Cline, custom agents — gains direct, structured access to every semantic operation Aura performs.

This is the primary integration surface for AI coding agents. CLI commands like `aura save` and `aura prove` are great for humans. The MCP server is how Claude (or any other model) actually *uses* Aura while it writes code. Instead of shelling out and parsing text, the agent calls a typed tool like `aura_log_intent({ intent: "..." })` and gets back a structured JSON response.

If you only do one Aura integration, do this one. Every other integration in this module is secondary.

## Why MCP instead of a CLI wrapper?

A CLI wrapper forces the agent to:

1. Remember command-line flags.
2. Parse human-readable output.
3. Handle exit codes as error signals.
4. Work around terminal quirks (TTY, color codes, pagers).

MCP replaces all of that with a typed request/response contract. The agent sees:

- A tool name (`aura_status`).
- A JSON schema for inputs.
- A JSON payload on the way back.

This is orders of magnitude more reliable. In practice, agents that use the MCP server make ~80% fewer Aura-related mistakes than agents driving the CLI.

## Setup

### Claude Code CLI

Claude Code auto-discovers MCP servers from `~/.claude/mcp.json` (global) or `.mcp.json` in the repo root (per-project).

```json
{
  "mcpServers": {
    "aura-vcs": {
      "command": "aura",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}
```

Restart Claude Code. Run `/mcp` in the REPL to confirm `aura-vcs` is connected and listing tools.

### Cursor

Cursor reads `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "aura-vcs": {
      "command": "aura",
      "args": ["mcp", "serve"]
    }
  }
}
```

Enable it in **Settings → Features → MCP**. Cursor's Composer will pick up the tools automatically.

### Claude Desktop

Claude Desktop uses `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, and the equivalent AppData path on Windows:

```json
{
  "mcpServers": {
    "aura-vcs": {
      "command": "/usr/local/bin/aura",
      "args": ["mcp", "serve"]
    }
  }
}
```

Use the absolute path to the `aura` binary — Claude Desktop does not inherit your shell's `$PATH`.

### Zed, Windsurf, Cline, and others

Any MCP-compliant client works. The command is always `aura mcp serve`. If the client speaks MCP, it speaks Aura.

## Tool Inventory

All tools use the `aura_` prefix. Tools are grouped by surface.

### Core state and intent

| Tool | Purpose |
|------|---------|
| `aura_status` | Session state, tracked nodes, team sync, zone claims. Call at session start. |
| `aura_log_intent` | Log the intent for the current commit. Auto-pushes to mothership. |
| `aura_prove` | Mathematically verify a behavioral goal. |
| `aura_pr_review` | AI-powered semantic PR review. |
| `aura_doctor` | Diagnose stuck sessions, orphaned snapshots, missing hooks. |
| `aura_suggest_edit` | Get AI-suggested fixes for violations. |

### Planning

| Tool | Purpose |
|------|---------|
| `aura_plan_discover` | Discover gray-area decisions, produce a wave plan. |
| `aura_plan_lock` | Lock plan decisions after human review. |
| `aura_plan_next` | Fetch the next wave to execute. |

### Snapshots and recovery

| Tool | Purpose |
|------|---------|
| `aura_snapshot` | Pre-edit file backup, with team-zone enforcement. |
| `aura_snapshot_list` | List available snapshots. |
| `aura_rewind` | Surgical, AST-level function revert. |

### Sessions and handover

| Tool | Purpose |
|------|---------|
| `aura_session_resume` | Resume a prior session. |
| `aura_session_summarize` | Summarize a session's work. |
| `aura_handover` | Dense XML payload for agent handoff. |
| `aura_orchestrate_status` | Multi-agent orchestration progress. |

### Team live sync

| Tool | Purpose |
|------|---------|
| `aura_live_impacts` | Cross-branch impact alerts for your deps. |
| `aura_live_resolve` | Mark an impact alert resolved. |
| `aura_live_sync_push` | Push function bodies to the mothership. |
| `aura_live_sync_pull` | Pull and AST-merge teammate changes. |
| `aura_live_sync_status` | Pending sync changes, active pushers. |

### Messaging

| Tool | Purpose |
|------|---------|
| `aura_msg_send` | Message a teammate or the whole team. |
| `aura_msg_list` | Read the team inbox. |
| `aura_sentinel_send` | Message another AI agent in the same repo. |
| `aura_sentinel_inbox` | Read messages from other AI agents. |
| `aura_sentinel_agents` | Enumerate active AI agents. |

### Zones and memory

| Tool | Purpose |
|------|---------|
| `aura_zone_claim` | Claim files or functions so other agents don't touch them. |
| `aura_memory_read` | Read long-term project memory. |
| `aura_memory_write` | Persist a fact to long-term memory. |

That is 28 first-class tools at the time of writing, with 29+ depending on your Aura version and enabled features (e.g. `aura_handover_pack`, `aura_memory_compact`).

## Examples

### Typical agent loop

A well-behaved agent runs this at the start of every task:

```json
{ "tool": "aura_status" }
```

The response includes `team.pending_pull`, `zones`, `unread_messages`, and `strict_mode_locked`. The agent then reacts:

- If `pending_pull`: call `aura_live_sync_pull`.
- If `unread_messages > 0`: call `aura_msg_list`.
- If the target file is in a `BLOCKED` zone: stop and ask the human.

Before each file edit:

```json
{ "tool": "aura_snapshot", "input": { "path": "src/auth/oauth.rs" } }
```

Before each commit:

```json
{
  "tool": "aura_log_intent",
  "input": {
    "intent": "Refactor retry_logic to use exponential backoff for rate limit compliance"
  }
}
```

After a logical unit of work:

```json
{ "tool": "aura_pr_review", "input": { "base": "main" } }
```

### Verifying a goal

```json
{
  "tool": "aura_prove",
  "input": { "goal": "User can authenticate via OAuth and session survives restart" }
}
```

Aura returns which logic nodes exist, which edges are wired, and any gaps. This is the same engine powering [semantic diff](/semantic-diff) and [aura-merge](/aura-merge).

## Configuration

The MCP server respects the same config as the CLI. The most common knobs:

```toml
# .aura/config.toml
[mcp]
# Restrict which tools the server exposes. Empty = all.
tools_allow = []
tools_deny = ["aura_memory_write"]

# Max concurrent tool calls.
max_inflight = 8

# Redact specific keys from tool responses before returning.
redact_keys = ["email", "ssh_key"]
```

For multi-repo setups, run one MCP server per repo. Agents can be connected to many at once; each appears as a separate server name in the client.

## Troubleshooting

**Tools not appearing in Claude Code.** Confirm `aura mcp serve` works from your shell. The MCP server logs to `.aura/logs/mcp.log`. Common cause: the binary path in `mcp.json` is wrong, or you restarted the client before the server bound its stdio.

**`aura_status` returns `"no session"`.** You are running the MCP server outside a git repository, or `aura init` was never run. Initialize the repo.

**`aura_snapshot` returns `TEAM_ZONE_BLOCKED`.** A teammate claimed the file. Either message them via `aura_msg_send` or ask the human to release the zone.

**Slow first call.** The MCP server lazily builds the AST index on first request. After that, calls are sub-100ms for most repos. For very large monorepos, pre-warm with `aura index --warm`.

**Tool denied by policy.** Check `[mcp].tools_deny` in `.aura/config.toml`. Some organizations disable `aura_memory_write` or `aura_zone_claim` for agents by default.

## Lifecycle of a Tool Call

Understanding what happens under the hood helps when debugging. A single `aura_log_intent` call flows through these stages:

1. **Transport.** The MCP client (Claude Code, Cursor) serializes a JSON-RPC request over stdio or TCP to the Aura MCP process.
2. **Schema validation.** The server validates the arguments against the declared JSON schema. Bad arguments get an `InvalidParams` error back immediately — they never touch the semantic engine.
3. **Session resolution.** The server looks up the current Aura session by `cwd` or explicit `repo` argument. If no session exists, it returns a typed `NoSession` error and suggests `aura init`.
4. **Policy check.** The `[mcp]` config is consulted for `tools_allow` / `tools_deny`. Denied tools return `PolicyDenied` before any work happens.
5. **Zone / strict-mode enforcement.** For edit-adjacent tools (`aura_snapshot`, `aura_log_intent`), the zone table is checked. Blocked zones fail fast with a descriptive error pointing at the owner.
6. **Execution.** The underlying command runs against the semantic DB. Results are serialized to JSON.
7. **Auto-push side effects.** For `aura_log_intent`, the resulting changed function bodies are queued for mothership push. The push is asynchronous — the tool call does not block on it.
8. **Response.** The envelope returns with a stable `status`, `data`, and optional `notifications` array (the source of the `🔄 SYNC` / `💬 TEAM` banners Claude reacts to).

Every tool response includes a `request_id` so logs can be correlated across the client, the MCP server, and the mothership.

## Security Model

The MCP server speaks on a local-only transport by default: Unix domain socket on macOS/Linux, named pipe on Windows, or stdio when launched by a client. Network exposure is opt-in and requires explicit `--bind 0.0.0.0:port`.

Trust boundary: the MCP server trusts its client. An attacker with access to your user account could invoke tools as you. This is the same trust model as the CLI. Do not expose the server over the network without a reverse proxy that authenticates callers.

Secrets never appear in MCP responses. The `redact_keys` config is applied before any response is written, including error bodies. Plugin-provided tools inherit the same redaction.

## See Also

- [CLAUDE.md integration](/claude-md-integration) — the protocol that tells Claude *when* to call each tool.
- [Mothership overview](/mothership-overview) — what powers `aura_live_*`.
- [What is Aura](/what-is-aura) — the semantic engine the MCP server exposes.
- [Semantic diff](/semantic-diff) — the kernel behind `aura_pr_review` and `aura_prove`.
- [Custom plugins](/custom-plugins) — add your own tools to the MCP surface.
- [Aura HTTP API](/aura-api-reference) — the lower-level API the MCP server wraps.