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`	Subprocess communicating via stdin/stdout

All servers support disabled: true to skip during startup and timeout (Go duration syntax, e.g. 30s, 1m) to control connection timeouts. Stdio servers support env for passing environment variables to the subprocess.

Environment Variables

Header values support environment variable expansion using ${VAR_NAME} syntax:

headers:
  Authorization: Basic ${MY_TOKEN}

Disabling Servers

Set disabled: true to skip a server during startup.

Deferred Tool Loading

Set deferred: true on a server to exclude its tools from the initial tool set. Tools are then loaded on demand via the LoadTools meta-tool, which reduces context usage in MCP-heavy setups.

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

The server still connects at startup; only tool registration is deferred.

Server Filtering

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

CLI flags (apply to all commands):

# Only connect to matching servers
aura run --include-mcps "context7,git*"

# Skip matching servers
aura run --exclude-mcps "portainer"

# Disable all MCP connections
aura run --exclude-mcps "*"

Feature config (features/mcp.yaml):

mcp:
  enabled: []              # default for --include-mcps (empty = connect all)
  disabled: ["portainer"]  # default for --exclude-mcps (empty = skip none)

CLI flags override feature config. Exclude takes precedence over include. Per-server disabled: true is independent — it’s an author-side toggle in the server definition, while filtering is a user-side override.

Filters are applied dynamically:

Agent switch — when switching agents via /agent or Shift+Tab, if the new agent’s MCP filter rules differ from the previous agent’s, MCP sessions are closed and reconnected with the new filter set.
Config reload — per-turn config reload reapplies MCP filters. Sessions that no longer pass the filter are closed; sessions that still pass keep their tools active. Use /reload to fully reconnect all servers from scratch.

Conditional Inclusion

Set condition: on a server to conditionally include its tools based on runtime state. The server still connects at startup — only tool visibility is affected.

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

When the condition is false, all tools from that server are excluded from the active tool set. Conditions are re-evaluated every turn. Invalid condition expressions are rejected at config load time. Per-tool conditions can be set via Tool Definitions — a ToolDef condition: on an MCP tool overrides the server-level condition.

MCP Tools

MCP tools appear with the mcp__ prefix in tool listings. For example, a tool search from server github appears as mcp__github__search.

Use /mcp to list connected servers and their available tools. Use /mcp reconnect to retry all failed servers, or /mcp reconnect <name> to retry a specific one.

Tool Filtering

Agent and mode configs can filter MCP tools using the mcp__* wildcard pattern:

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