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:

Remember command-line flags.
Parse human-readable output.
Handle exit codes as error signals.
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).

{
  "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:

{
  "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:

{
  "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:

{ "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:

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

Before each commit:

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

After a logical unit of work:

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

Verifying a goal

{
  "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 and aura-merge.

Configuration

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

# .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:

Transport. The MCP client (Claude Code, Cursor) serializes a JSON-RPC request over stdio or TCP to the Aura MCP process.
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.
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.
Policy check. The [mcp] config is consulted for tools_allow / tools_deny. Denied tools return PolicyDenied before any work happens.
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.
Execution. The underlying command runs against the semantic DB. Results are serialized to JSON.
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.
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.