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

AEGIS provides a hosted MCP endpoint on GCP Cloud Run. No local installation required — connect any MCP-compatible client directly.

Authentication uses a Bearer token (same API key from the portal).

Claude Code (.mcp.json)

{
  "mcpServers": {
    "aegis": {
      "type": "streamable-http",
      "url": "https://aegis-mcp-980022636831.us-central1.run.app/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your API key from the portal.

Health Check

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

curl https://aegis-mcp-980022636831.us-central1.run.app/health

Local MCP Server (stdio)

For local development or air-gapped environments, run the MCP server locally via stdio.

Claude Code Integration

pip install -e ".[mcp]"

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": []
    }
  }
}

This exposes 7 tools to Claude Code: aegis_evaluate_proposal, aegis_quick_risk_check, aegis_check_thresholds, aegis_get_scoring_guide, aegis_crypto_status, aegis_list_decisions, and aegis_get_decision.

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 (ECS/hosted)

In production (ECS Fargate), the server runs with streamable-http behind an internal ALB, exposed publicly via API Gateway HTTP API with Unkey Bearer token authentication. A /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 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)

Tools

aegis_evaluate_proposal

Full governance gate evaluation via pcw_decide(). Evaluates a proposal through all six quantitative gates (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:

aegis_get_decision

Get a specific governance decision by ID. Returns the full decision record including input context, all gate results, rationale, next steps, and audit hash.

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