MCP Support

Aura supports the Model Context Protocol (MCP) for connecting to external tool servers.

Configuration

MCP servers are defined in .aura/config/mcp/*.yaml:

server-name:
  type: http
  url: https://example.com/mcp
  headers:
    Authorization: Bearer ${API_TOKEN}

local-tool:
  type: stdio
  command: go
  args: [run, ./mcp-server/main.go]

disabled-server:
  type: http
  url: https://example.com/mcp
  disabled: true

Transport Types

Type	Fields	Description
`http`	`url`, `headers`, `timeout`	HTTP-based MCP server
`stdio`	`command`, `args`, `env`, `timeout`, `sandbox`	Subprocess via stdin/stdout

timeout bounds connecting (start, initialize, tool listing; default 10s). Tool calls have no deadline: they end when they finish or the run is cancelled.

command, args, env, url and headers expand $VAR and ${VAR} from the environment. A reference to an unset variable is an error (a variable that is set but empty is allowed), so a missing token or path never silently becomes an empty string.

Required Servers

crossroads:
  command: uv
  args: [run, --script, /opt/trusted/authoring_mcp.py, --workspace, .]
  required: true

A required server that fails to start, initialize or list its tools fails startup on every path (interactive, aura run, tasks, aura serve) instead of continuing without its tools. Other servers that fail are reported and skipped. A required server that fails to reconnect on /reload or an agent switch is an error.

Sandboxed Stdio Servers

sandbox: true launches a stdio server under the session’s Landlock restrictions — see Sandboxing. It is rejected for http servers, which cannot be confined locally.

Results, Errors and Cancellation

Text content of a result is returned to the model. A result with isError: true is a tool error: the call is recorded as failed, with the content as the error message.
When a run is cancelled while a tool call is in flight, Aura sends notifications/cancelled for that request so the server can stop its work; the call is recorded as failed and the session stays usable.
Each server’s stderr is drained continuously (and logged with --debug), so a server that logs heavily never blocks on a full pipe. The last lines are included in connection errors.

Deferred Tool Loading

Set deferred: true to exclude a server’s tools from the initial tool set. Tools load on demand via the LoadTools meta-tool, reducing context usage in MCP-heavy setups. The server still connects at startup — only tool registration is deferred.

Alternatively, defer individual MCP tools via glob patterns in features/tools.yaml instead of deferring the entire server: deferred: ["mcp__github__*"].

github:
  deferred: true
  command: npx
  args: ["-y", "@modelcontextprotocol/server-github"]
  env:
    GITHUB_TOKEN: ${GITHUB_TOKEN}

Server Filtering

Filter which servers connect using glob patterns — same system as tool filtering.

aura run --include-mcps "context7,git*"
aura run --exclude-mcps "portainer"
aura run --exclude-mcps "*"   # disable all MCP

Feature config defaults (features/mcp.yaml):

mcp:
  enabled: [] # empty = connect all
  disabled: ["portainer"]

CLI flags override feature config. Exclude takes precedence over include. Per-server disabled: true is an author-side toggle; filtering is a user-side override.

Filters are reapplied on agent switch (if MCP filter rules differ) and on config reload. Use /reload to fully reconnect all servers from scratch.

Conditional Inclusion

Set condition: on a server to exclude its tools based on runtime state. The server still connects — only tool visibility is affected. Conditions are re-evaluated every turn.

heavy-server:
  condition: "model_params_gt:7"
  type: http
  url: https://example.com/mcp

Conditions use the same expression syntax as /assert — see Slash Commands.

MCP Tools

MCP tools appear with the mcp__ prefix — e.g., mcp__github__search. Use /mcp to list connected servers and tools, /mcp reconnect to retry failed servers.

Agent and mode configs can filter MCP tools:

tools:
  disabled:
    - mcp__* # Disable all MCP tools