MCP Tools Reference

AEGIS MCP Server -- Model Context Protocol interface for agentic AI governance.

The AEGIS MCP server exposes governance gates as MCP tools that AI agents (Claude Code, Codex, custom agents) can call to evaluate proposals before taking action.

Hosted MCP Endpoint (not served)

The hosted MCP endpoint on GCP Cloud Run is offline (September 2026); see undercurrentholdings.com/status. The configuration below documents the interface.

Authentication uses a Bearer token (an AEGIS API key).

Claude Code (.mcp.json)

Claude Code's streamable-HTTP transport is selected with "type": "http" (Claude Code 2.x+ resolves "http" to the MCP Streamable HTTP transport per the 2025-11-25 spec — "streamable-http" is silently rejected and shows as invalid in /doctor).

{
  "mcpServers": {
    "aegis": {
      "type": "http",
      "url": "https://mcp.aegis.undercurrentholdings.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Or add the server from the command line:

claude mcp add --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  aegis https://mcp.aegis.undercurrentholdings.com/mcp

Replace YOUR_API_KEY with an AEGIS API key.

Health Check

The /health route is public (no authentication required):

curl https://mcp.aegis.undercurrentholdings.com/health

Local MCP Server (stdio)

Run the MCP server locally via stdio — installable from PyPI. Its tools call the hosted API, which is offline, so they return an error. Without an API key the server uses sandbox mode; with AEGIS_API_KEY set in the server's environment, the key-required tools (decision history, usage reports, risk checks) are enabled.

Claude Code Integration

pip install "aegis-governance[mcp]"   # Python >= 3.10

Or in one step:

claude mcp add aegis -- aegis-mcp-server

Add a .mcp.json to the project root (preferred — portable and version-controllable):

{
  "mcpServers": {
    "aegis": {
      "type": "stdio",
      "command": "aegis-mcp-server"
    }
  }
}

Or add to your project's .claude/settings.json:

{
  "mcpServers": {
    "aegis-governance": {
      "command": "aegis-mcp-server",
      "args": []
    }
  }
}

The PyPI package exposes 6 tools to Claude Code: aegis_evaluate_proposal, aegis_quick_risk_check, aegis_health, aegis_list_decisions, aegis_get_decision, and aegis_get_usage. The full 10-tool surface (thresholds, scoring guides, proposal records, crypto status) was served by the hosted endpoint (offline since September 2026). Running the server from source (pip install -e ".[engine,mcp]" in the private repository: the extras the MCP image needs for gate evaluation and persistence) gives in-process gate evaluation. That server-side aegis_evaluate_proposal records each decision the same way the REST /evaluate path does: it appends a hash-chained audit entry and stores the decision (best-effort) for the authenticated customer (see Audit Logging).

Starting the Server

The MCP server uses the official MCP Python SDK (FastMCP) and supports two transports:

aegis-mcp-server                                          # stdio (default, for Claude Code)
aegis-mcp-server --transport streamable-http --port 8080  # HTTP (hosted)

When the hosted service ran, the server used GCP Cloud Run with streamable-http transport. Authentication uses the MCP Python SDK's TokenVerifier contract backed by Unkey: every request to /mcp must carry an Authorization: Bearer <api-key> header, and the verified customer_id from the token is used by tools instead of any client-supplied argument. A public /health endpoint is available for container and load-balancer health checks.

Rate Limiting

The server includes a token bucket rate limiter (CoSAI MCP-T10 compliance).

• Default: 60 requests per minute
• Configurable via AegisConfig.mcp_rate_limit
• Set to 0 to disable
• Exceeding the limit returns an error in the tool response

Audit Logging

Every evaluated aegis_evaluate_proposal invocation is logged with:

• SHA-256 hash of parameters (first 16 hex chars, PII-safe)
• Decision status
• Latency in milliseconds
• Caller ID (from agent_id argument)

A call refused for its customer id (customer_id_required, reserved_customer_id, invalid_customer_id) is refused before evaluation: it produces no decision, no audit log line, no telemetry, and does not consume a rate-limit token.

Each decision is also appended to the hash-chained audit trail, using the same shared code path as the REST /evaluate endpoint, so the same decision produces the same audit_hash:

• Authenticated (verified Bearer token, or AEGIS_CUSTOMER_ID in stdio mode): the entry is appended to the customer's durable chain and the response reports "audit_chain": "persisted". The decision is also stored, best-effort, so aegis_list_decisions and aegis_get_decision can return it. audit_chain reports the chain append only; decision_stored reports the store. A storage failure is logged server-side, does not turn the response into an error, and sets "decision_stored": false — the chain entry exists but the decision cannot be retrieved. Until ROADMAP G136 closes, expect false in production: storage needs the PII-encryption keys (AEGIS_MASTER_KEK_*), which the deploy path does not yet provide.
• Unauthenticated (no customer id): the entry goes to a process-local, non-durable in-memory chain and no decision is stored. The response reports "audit_chain": "in-memory" and "decision_stored": false. This applies only to development stages; fail-closed stages refuse the call (below). In development stages an authenticated call also reports in-memory when the database is unavailable. Without DATABASE_URL, development stages persist to a local SQLite file, .aegis/aegis.db in the working directory, and report persisted for it.
• Fail-closed: for an authenticated call in fail-closed stages (any AEGIS_STAGE other than development, dev, test, local, ci, e2e, or unset/empty, compared trimmed and case-insensitively — so production, staging, and unknown values such as prod fail closed), if the audit chain cannot be written, the tool returns {"error": "audit_persistence_unavailable", "error_class": "<class>"} instead of a decision (the REST equivalent is HTTP 503). Retry later. An unauthenticated call (no customer id, e.g. stdio without AEGIS_CUSTOMER_ID) in a fail-closed stage returns {"error": "customer_id_required"} and no decision: there would be no durable chain to record it in.
• Reserved ids: a reserved customer id (the /ready probe sentinel or the Layer-D proposal namespace) returns {"error": "reserved_customer_id"}, and a whitespace-only customer id returns {"error": "invalid_customer_id"}.

Persisting requires the database extras: [engine] (includes the PostgreSQL driver), or [persistence] for SQLite only. Without them, an authenticated evaluation reports "audit_chain": "in-memory" in development stages and returns audit_persistence_unavailable in fail-closed stages.

Tools

aegis_evaluate_proposal

Full governance gate evaluation via pcw_decide(). Evaluates a proposal through all six gate checks (Risk, Profit, Novelty, Complexity, Quality, Utility) and returns a structured decision with per-gate details and rationale.

Required parameters:

Optional parameters:

Utility auto-synthesis: If utility_result is not provided (the common case), the MCP server auto-synthesizes it from profit_baseline/profit_proposed using symmetric PERT three-point estimation (±20% spread) with a profit delta epsilon clamp of 0.001. This matches CLI and REST API behaviour — all three surfaces produce identical utility gate results for the same inputs.

Response fields:

aegis_quick_risk_check

Quick risk threshold check (risk_score < threshold).

Warning: This is a simplified check without Bayesian evaluation. For governance decisions, use aegis_evaluate_proposal instead.

Required parameters:

Optional parameters:

Response fields:

aegis_check_thresholds

Introspect all six gate thresholds and current configuration. Call this before submitting proposals to understand gate behavior and parameter values.

Parameters: None required.

Response fields:

aegis_get_scoring_guide

Get domain-specific parameter derivation guidance. Returns formulas, range guides, common mistakes, and worked examples showing how to map domain metrics to AEGIS parameters.

Recommended workflow:

1. aegis_check_thresholds — understand gate configuration
2. aegis_get_scoring_guide(domain) — get derivation formulas for your domain
3. aegis_evaluate_proposal(...) — submit with derived values

Parameters:

Response fields:

Available domains:

aegis_crypto_status

Check availability of all AEGIS cryptographic providers (signatures, encryption, key management). Returns which providers are installed and active.

Parameters: None.

Response fields:

aegis_list_decisions

List governance decisions for the current customer. Returns recent decisions with status, confidence, proposal summary, and gate results.

Parameters:

Response fields:

Each entry in decisions is the cleaned persisted decision record — the internal storage keys (pk, sk, entity_type, ttl) are stripped, and Decimal values are coerced to JSON numbers. The remaining fields reflect exactly what was stored for that decision.

On failure: {"error": "customer_id required ..."} when no customer id resolves; {"error": "invalid_customer_id"} for a whitespace-only one; {"error": "month must be YYYY-MM (year + 01-12)"} for a malformed month; otherwise {"error": "Failed to retrieve decisions", "error_class": "<ExceptionClass>"} (class name only, never the exception message).

aegis_get_decision

Get a specific governance decision by ID. Returns the full stored decision record: gate results, rationale, next steps, audit-chain hashes, and the proposal context recorded with it.

Parameters:

Response fields:

The table lists the main fields; a record may carry more (for example customer_id, gates_passed, gates_failed, failing_gates, and drift or calibration details when present). Records stored before the G55 context enrichment may lack the proposal-context fields. On failure: {"error": "customer_id required ..."}, {"error": "invalid_customer_id"} (whitespace-only id), {"error": "Decision <id> not found"}, or {"error": "Failed to retrieve decision", "error_class": "<ExceptionClass>"}.

aegis_record_proposal

Record a Layer-D meta-improver proposal (one Tier-B verdict, or a forward-compat Track-D proposal) into the current customer's per-customer SHA-256 audit chain (aegis_layer_d_proposals). Returns the chain hash + 1-indexed sequence. A duplicate (customer_id, proposal_id) is rejected as a semantic error (the proposal is already on the chain).

Parameters:

Response fields:

On failure returns {error, error_class} (class-name only — never raw SQL or connection detail, per CWE-209). A duplicate (customer_id, proposal_id) is rejected rather than re-chained.

aegis_list_proposals

List the current customer's Layer-D meta-improver proposals in insertion (chain) order, paginated. Returns each proposal's verdict, confidence, gate scores, tier-B voters, and chain hashes. Use to review recorded Tier-B verdicts or audit the Layer-D chain.

Parameters:

Response fields:

aegis_verify_proposals

Verify the integrity of the current customer's Layer-D proposal chain. Recomputes each SHA-256 link in insertion order and reports whether the chain is intact.

Parameters:

Response fields:

Integration with MCP Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aegis-governance": {
      "command": "aegis-mcp-server",
      "args": []
    }
  }
}

Custom MCP Clients

Connect via stdio using the MCP Python SDK:

from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

params = StdioServerParameters(command="aegis-mcp-server", args=[])
async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "aegis_evaluate_proposal",
            arguments={
                "proposal_summary": "Add caching layer",
                "estimated_impact": "medium",
                "risk_score": 0.2,
                "complexity_score": 0.7,
            },
        )

Security

SSRF Protection

Telemetry URLs provided via telemetry_url are validated with a resolve-then-validate approach:

• DNS resolution is performed first to catch DNS rebinding
• Private, loopback, link-local, reserved, and CGNAT addresses are blocked
• Only https:// schemes are accepted in production

Input Validation

• All numeric parameters reject NaN, Inf, and -Inf
• Boolean parameters reject non-boolean types (prevents Python truthiness confusion)
• estimated_impact is validated as a string enum
• The validate_float() helper preserves legitimate falsy values like 0 and 0.0