aald-mcp

Model Context Protocol adapter for the Agent Action Ledger daemon.

aald-mcp bridges MCP-compatible AI clients (Claude, Cursor, VS Code Copilot, etc.) to a running aald daemon. Each capability you configure in AAL becomes an MCP tool, and every invocation is authenticated, rate-limited, and recorded in AAL's tamper-evident audit ledger.

This server is MIT-licensed open source. The aald daemon it connects to is a separate, commercially-licensed product available at mmediasoftwarelab.com.

---

How it works

MCP client (Claude, Cursor, …)
        │  MCP tool call
        ▼
   aald-mcp  ──── POST /v1/execute ────▶  aald daemon
                  Bearer <service_key>         │
                                        audit ledger (SQLite)
                                        capability driver (SMTP / HTTP)

aald-mcp reads the capabilities section of your AAL config, registers each capability that has an mcp_schema block as an MCP tool, and forwards tool calls to the daemon as authenticated execution requests. The daemon handles authorization, rate limiting, encryption, and ledger writes. aald-mcp is stateless.

---

Prerequisites

• A running aald daemon (v1.x). Get it here.
• Go 1.21+ (to build from source) or a pre-built binary from the releases page.

---

Installation

Pre-built binary (recommended):

Download the binary for your platform from the releases page and place it on your PATH.

Build from source:

git clone https://github.com/mmediasoftwarelab/aald-mcp.git
cd aald-mcp
go build -o aald-mcp .

---

Quick start

aald-mcp reads the same YAML config file as the aald daemon. The only sections it uses are server, mcp, license, and capabilities.

1. Enable MCP in your config and add mcp_schema blocks to the capabilities you want to expose:

server:
  port: 7340
  host: 127.0.0.1
  tls:
    disabled: true          # set false and add cert/key in production

mcp:
  enabled: true
  port: 7341
  service_key: "replace-with-mcp-service-key"
  tls:
    disabled: true          # set false and add cert/key in production

capabilities:
  send_email:
    driver: smtp
    config:
      host: smtp.example.com
      port: 587
      username: agent@example.com
      password: "smtp-password"
    rate_limit:
      per_hour: 100
      per_day: 500
    mcp_schema:
      properties:
        to:
          type: string
          description: Recipient email address
        subject:
          type: string
          description: Email subject line
        body:
          type: string
          description: Plain text email body
        description:
          type: string
          description: Human-readable intent for audit trail
      required: [to, subject, body, description]

2. Start the daemon, then start aald-mcp:

aald -config config.yaml &
aald-mcp -config config.yaml

3. Point your MCP client at http://localhost:7341/sse (or https:// if TLS is enabled).

---

Configuration reference

Only the fields aald-mcp reads are listed here. See the aald daemon docs for the full schema.

server

Field	Default	Description
server.host	0.0.0.0	Hostname/IP where the aald daemon is listening
server.port	7340	Port the aald daemon is listening on
server.tls.disabled	false	Whether the daemon's TLS is off (controls the scheme used for daemon requests)

mcp

Field	Default	Description
mcp.enabled	false	Must be true for aald-mcp to start
mcp.port	7341	Port aald-mcp listens on
mcp.service_key	—	Bearer token sent to the daemon. Must match mcp.service_key in the daemon config
mcp.tls.disabled	false	Disable TLS on the MCP server itself
mcp.tls.cert	—	Path to TLS certificate (required when TLS is enabled)
mcp.tls.key	—	Path to TLS private key (required when TLS is enabled)

capabilities[*].mcp_schema

Only capabilities with an mcp_schema block are registered as MCP tools. Capabilities without one are invisible to MCP clients.

capabilities:
  my_capability:
    # ... driver config ...
    mcp_schema:
      properties:
        param_name:
          type: string          # JSON Schema type
          description: "..."    # shown to the AI client
      required: [param_name]

TLS policy

Scenario	server.tls.disabled	mcp.tls.disabled
Local dev / unlicensed	true	true
Production (licensed)	false (required)	false (required)

Licensed deployments enforce TLS on both the daemon and the MCP server. aald-mcp will refuse to start if the policy is violated.

---

License

MIT — see LICENSE.

The aald daemon is separately licensed commercial software. Contact mmediasoftwarelab.com for licensing.