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.

Starting the Server¶

The MCP server supports two transport modes: stdio (default) and HTTP.

stdio Transport (Default)¶

Standard MCP pattern for local agent integration. The server reads JSON-RPC requests from stdin and writes responses to stdout.

aegis-mcp-server
aegis-mcp-server --config /path/to/config.yaml

HTTP Transport¶

Streamable HTTP transport (MCP spec 2025-03-26) for network-accessible deployment.

# Listen on localhost only (default)
aegis-mcp-server --transport http --port 8080

# Listen on all interfaces
aegis-mcp-server --transport http --host 0.0.0.0 --port 8080

# With custom config
aegis-mcp-server --transport http --port 8080 --config /path/to/config.yaml

Server Options¶

Protocol Details¶

The server implements JSON-RPC 2.0 over the MCP protocol (version 2025-03-26).

Supported Methods¶

Server Capabilities¶

The initialize response includes:

• Protocol version: 2025-03-26
• Server name: aegis-governance
• Tools capability: available
• AMTSS schema signing (experimental): available when crypto dependencies are installed, providing tool schema integrity verification

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 JSON-RPC error code -32000

Audit Logging¶

Every tool invocation is logged with:

• Tool name
• SHA-256 hash of parameters (first 16 hex chars, PII-safe)
• Decision: ALLOW, DENY, or ERROR
• 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:

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:

Integration with MCP Clients¶

Claude Desktop¶

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "aegis-governance": {
      "command": "aegis-mcp-server",
      "args": ["--config", "/path/to/config.yaml"]
    }
  }
}

Claude Code¶

The server is automatically available when configured in the MCP server list. Claude Code can call tools like:

Use aegis_check_thresholds to see current gate configuration, then
use aegis_evaluate_proposal to evaluate the proposed change.

Custom MCP Clients¶

Connect via stdio by spawning the server process:

import subprocess
import json

proc = subprocess.Popen(
    ["aegis-mcp-server"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    text=True,
)

# Initialize
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {},
}
proc.stdin.write(json.dumps(request) + "\n")
proc.stdin.flush()
response = json.loads(proc.stdout.readline())

# Call a tool
request = {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "aegis_evaluate_proposal",
        "arguments": {
            "proposal_summary": "Add caching layer",
            "estimated_impact": "medium",
            "risk_score": 0.2,
            "complexity_score": 0.7,
        },
    },
}
proc.stdin.write(json.dumps(request) + "\n")
proc.stdin.flush()
response = json.loads(proc.stdout.readline())
decision = json.loads(response["result"]["content"][0]["text"])
print(f"Status: {decision['status']}")

HTTP Client¶

# Initialize
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# Check thresholds
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"aegis_check_thresholds","arguments":{}}}'

# Evaluate proposal
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"aegis_evaluate_proposal",
      "arguments":{
        "proposal_summary":"Deploy new service",
        "estimated_impact":"high",
        "risk_score":0.3,
        "complexity_score":0.8
      }
    }
  }'

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

Schema Signing (AMTSS Protocol v1)¶

When crypto dependencies are installed, the server signs tool schemas using Ed25519 with RFC 8785 JSON canonicalization. This provides integrity verification for tool definitions (CoSAI MCP-T6 compliance).

Signing metadata is included in tools/list responses under the _meta["com.aegis.governance/toolSchemaSigning"] key, and keyset information is advertised in initialize under capabilities.experimental.toolSchemaSigning.

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 _float_arg() helper preserves legitimate falsy values like 0 and 0.0

Error Handling¶

Tool execution errors are returned as MCP tool results with isError: true rather than JSON-RPC error responses, following MCP protocol conventions.