AIR Controls MCP Server

April 11, 2026 · View on GitHub

Runtime visibility layer for AI agents — An MCP (Model Context Protocol) server that automatically logs agent actions into AIR Controls with full audit chain integrity.

This server lets Cursor, Claude Code, Windsurf, and any other MCP-compatible AI development tool automatically capture what agents are doing, with complete metadata for compliance, security, and debugging.

Features

Automatic action logging - Capture LLM calls, tool usage, API requests, file edits, commands, and errors
HMAC-SHA256 audit chain - Cryptographic proof that event history hasn't been tampered with
Metadata tracking - Tokens, cost, duration, risk scoring, and custom fields
Agent control - Pause/resume agents with a single command (kill switch)
Chain verification - Verify integrity of the entire audit trail
Multi-tool support - Works with Cursor, Claude Code, Windsurf, and any MCP client

Installation

1. Install the package

pip install air-controls-mcp

This installs both the MCP server and the underlying air-controls storage layer.

2. Configure your AI tool

Choose your tool below and add the MCP server configuration to its settings file.

Cursor

Add to ~/.cursor/mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "air-controls": {
      "command": "air-controls-mcp",
      "env": {
        "AIR_CONTROLS_DB": "~/.air-controls/events.db"
      }
    }
  }
}

Location: Open Cursor settings (Cmd+, or Ctrl+,), search for "MCP", and edit the mcp.json file in the user directory.

Claude Code (VS Code Extension)

Add to ~/.claude/mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "air-controls": {
      "command": "air-controls-mcp",
      "env": {
        "AIR_CONTROLS_DB": "~/.air-controls/events.db"
      }
    }
  }
}

Location: In VS Code, open the Claude Code sidebar, click settings, and select "Edit MCP settings" to access the mcp.json file.

Windsurf

Add to ~/.windsurf/mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "air-controls": {
      "command": "air-controls-mcp",
      "env": {
        "AIR_CONTROLS_DB": "~/.air-controls/events.db"
      }
    }
  }
}

Location: Open Windsurf settings, search for "MCP", and edit the configuration file.

Custom Tools / Generic MCP Clients

For any other MCP-compatible tool, add the configuration to its MCP settings file:

{
  "mcpServers": {
    "air-controls": {
      "command": "air-controls-mcp",
      "env": {
        "AIR_CONTROLS_DB": "~/.air-controls/events.db",
        "AIR_AGENT_NAME": "my-custom-agent"
      }
    }
  }
}

3. Restart your tool

Restart Cursor, Claude Code, Windsurf, or your MCP client. The AIR Controls tools should now be available.

Usage

Once configured, you have access to these tools in any conversation:

log_action

Log an agent action (the primary tool). Required parameters:

agent_name - Display name for your agent
action_type - One of: llm_call, tool_use, api_call, file_edit, command_run, decision, error
description - Human-readable summary of what happened

Optional parameters:

raw_action - Technical detail (JSON, traceback, code, etc.)
tokens_used - Token count for LLM calls
cost_usd - Cost in USD
duration_ms - Execution duration in milliseconds
risk_score - Risk assessment: low, medium, or high

Example:

Log this agent action:
- Agent: my-research-bot
- Type: llm_call
- Description: Searched for recent AIR Act guidelines using Claude 3.5 Sonnet
- Tokens: 4200
- Cost: 0.0315
- Duration: 2100ms
- Risk: low

get_status

Get overview of all monitored agents and recent activity. Shows:

Total agents under monitoring
Status of each agent (ACTIVE or PAUSED)
Event counts and error counts
Total cost across all agents

Example:

Get a status report of all monitored agents

get_timeline

Get event timeline for a specific agent. Shows the most recent events in chronological order.

Parameters:

agent_name - Name of the agent
limit - Number of events to show (default: 20)

Example:

Show me the timeline for my-research-bot with the last 30 events

pause_agent

Pause an agent (kill switch). Stops the agent from taking further actions.

Parameters:

agent_name - Name of the agent to pause

Example:

Pause the my-research-bot agent

resume_agent

Resume a previously paused agent.

Parameters:

agent_name - Name of the agent to resume

Example:

Resume my-research-bot

verify_chain

Verify the HMAC-SHA256 audit chain integrity. Checks that the event history hasn't been tampered with.

Parameters:

agent_name - Optional. If omitted, verifies all agents.

Example:

Verify the audit chain for my-research-bot

Or to verify all agents:

Verify the audit chain for all agents

Variable	Purpose	Default
`AIR_CONTROLS_DB`	Path to SQLite database file	`~/.air-controls/events.db`
`AIR_AGENT_NAME`	Override detected agent name	Auto-detected from tool
`AIR_FRAMEWORK`	Framework identifier	`unknown`

Example:

export AIR_CONTROLS_DB=/custom/path/events.db
export AIR_AGENT_NAME=my-research-agent
export AIR_FRAMEWORK=langchain

air-controls-mcp

Database

The MCP server uses SQLite for storage with:

HMAC-SHA256 signatures for audit chain integrity
Automatic schema initialization
Configurable path (default: ~/.air-controls/events.db)

The database is created automatically on first use.

Architecture

Your AI Tool (Cursor/Claude Code/Windsurf)
       ↓
    MCP Protocol
       ↓
AIR Controls MCP Server (this package)
       ↓
air_controls.EventStore
       ↓
SQLite Database with HMAC-SHA256 Chain

The server:

Receives action logs from your AI tool via the MCP protocol
Auto-detects which tool is calling it
Auto-creates agents on first use
Stores actions with complete metadata
Maintains cryptographic audit chain for compliance

Examples

Logging a complex research session

Log this comprehensive agent action:
- Agent: research-team
- Type: api_call
- Description: Queried EU AI Act regulatory database for Article 9 requirements
- Raw: {"endpoint": "/api/v2/eu-ai-act", "method": "GET", "params": {"article": 9}}
- Tokens: 1200
- Cost: 0.008
- Duration: 3400ms
- Risk: medium

Monitoring multiple agents

Get a status report on all agents I've created

Compliance verification

Verify the entire audit chain to ensure no events were tampered with

Emergency stop

Pause the autonomous-trading-bot agent immediately

Compliance & Security

HMAC-SHA256 audit chain - Cryptographic proof of event integrity
Immutable records - Events are append-only; can never be modified
Full metadata - Complete context for every action (risk, cost, duration, tokens)
Chain verification - Detect tampering with cryptographic validation
Agent pause/resume - Emergency control over agent behavior

Perfect for:

EU AI Act compliance (Articles 10, 12, 14, 15)
SOX compliance - Audit trails for financial AI systems
ISO 42001 - AI Management System
Internal governance - Track and control AI agent behavior
Debugging - Understand what agents did and why
Cost tracking - Attribution of LLM spend to specific agents and actions

Documentation - https://github.com/airblackbox/air-controls-mcp
Issues - https://github.com/airblackbox/air-controls-mcp/issues
Discussions - https://github.com/airblackbox/air-controls-mcp/discussions

Built with the Model Context Protocol by Anthropic. Part of the AIR Controls ecosystem for AI agent observability and compliance.

AIR Controls MCP Server

Features

Installation

1. Install the package

2. Configure your AI tool

Cursor

Claude Code (VS Code Extension)

Windsurf

Custom Tools / Generic MCP Clients

3. Restart your tool

Usage

log_action

get_status

get_timeline

pause_agent

resume_agent

verify_chain

Resources

air-controls://agents

air-controls://status

Environment Variables

Database

Architecture

Examples

Logging a complex research session

Monitoring multiple agents

Compliance verification

Emergency stop

Compliance & Security

Contributing

License

Support