@agledger/mcp-server

The official MCP server for the AGLedger API: change control for AI agents. A self-hosted notary that records every change an agent makes, signed and hash-chained, and gates the ones that matter.

Connects any MCP-compatible AI agent (Claude, Cursor, Windsurf, etc.) to the AGLedger API with 2 universal API-pass-through tools plus an offline audit verifier. No SDK code required. Just point your agent at this server.

Learn more

agledger.ai: what AGLedger is and who needs it
How it works walks the lifecycle: record, completion, verdict
Glossary: canonical definitions of Record, Completion, SCITT Receipt, Verdict, Settlement Signal
MCP Server guide: installation and agent workflow

Install

npm install -g @agledger/mcp-server

Quick Start

Add to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "agledger": {
      "command": "agledger-mcp",
      "args": [
        "--api-key", "your-api-key",
        "--api-url", "https://your-agledger-instance"
      ]
    }
  }
}

Both flags are required. AGLedger is self-hosted, so there is no default server to call: without --api-url the server exits before it accepts a connection.

Or run directly:

agledger-mcp --api-key <key> --api-url <url>

Exit codes: 0 clean, 1 runtime failure, 2 usage or configuration error (missing flag, unknown flag), so a launcher can tell a misconfiguration from a crash.

Tools

Tool	Description
`agledger_discover`	Returns API health, your identity, available scopes, and a quickstart workflow. Call this first.
`agledger_api`	Make any AGLedger API call (method, path, params). Every POST carries a generated `Idempotency-Key`; pass `idempotencyKey` to reuse the first attempt's key when retrying a call that may already have landed. The API returns `nextSteps` on every response for self-guided workflow discovery.
`agledger_verify`	Verify a record audit export offline (COSE_Sign1 envelopes per RFC 9052, hash chain + envelope signatures, Ed25519 or ES256). No network calls. Returns `valid`, `verifiedEntries`, and a `brokenAt` pointer with a canonical failure `code` on failure. Pass `publicKeys` to supply keys out of band and `requireOutOfBandKeys` for an independent audit that refuses the export's embedded keys. Built on the shared `@agledger/verify-core`.

Resources

Both are fetched live from the running instance, so neither can go stale.

Resource	Description
`agledger://llms.txt`	The API's agent-oriented documentation narrative (the llms.txt convention): what the product does, the vocabulary, and how records, completions, gates and webhooks fit together. Read this first if you are new to the API.
`agledger://openapi`	The OpenAPI 3.0 specification, for exact routes and request/response shapes.

Agent workflow

The agledger_discover tool returns a quickstart workflow that guides agents through the accountability flow:

GET /v1/schemas -- list available Record types
GET /v1/schemas/{type} -- get required fields and examples
POST /v1/records -- create a record
POST /v1/records/{id}/completions -- submit a completion (evidence) when done

Every API error response includes a suggestion field with actionable recovery guidance -- agents can self-correct without human intervention.

Configuration

Flag	Env Var	Description
`--api-key`	`AGLEDGER_API_KEY`	AGLedger API key (required)
`--api-url`	`AGLEDGER_API_URL`	API base URL of your instance (required). AGLedger is self-hosted, so there is no default; the server refuses to start without it.

What is AGLedger?

AGLedger is the accountability layer for automated operations. It notarizes what was agreed to, by whom, and when, and tracks the delegation of that agreement through other systems.

Records -- structured commitments with acceptance criteria and tolerance bands
Completions -- performer evidence recording what was reported to be done
Verdicts -- principal accept/reject decisions on a Completion (the Gate), with settlement signals
Audit chain -- notarized records as COSE_Sign1 envelopes, hash-chained, Ed25519-signed, tamper-evident, verifiable offline

Learn more at agledger.ai | API docs

Each self-hosted AGLedger instance also serves interactive Swagger UI at {AGLEDGER_API_URL}/docs.

Requirements

Node.js >= 24
A running self-hosted AGLedger API instance and an API key (see the self-hosted install guide at agledger.ai)

License

Proprietary. See LICENSE.

AGLedger is a trademark of AGLedger LLC, and Settlement Signal is a pending trademark of AGLedger LLC. All other trademarks are the property of their respective owners. Patent pending.