@agledger/mcp-server
OfficialConnects an MCP-compatible agent to a self-hosted AGLedger API for discovery, API operations, and offline audit verification.
agledger_discover: Get API health, caller identity, available scopes, and a quickstart workflow.agledger_api: Call any AGLedger/v1/endpoint with GET/POST/PUT/PATCH/DELETE; pass query params or JSON body, with generated/reusable idempotency keys andnextStepsguidance.agledger_verify: Verify an audit export offline (COSE_Sign1, hash chain, signatures), with optional out-of-band public keys, key pinning/requirement, and detailed failure codes.Read live
agledger://llms.txtandagledger://openapiresources for API documentation and exact schemas.Authenticate with an API key or OIDC token source, and optionally act on behalf of another party via delegation token.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@agledger/mcp-server discover available record types and create a new record for a software deployment"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@agledger/mcp-server
The official MCP server for the AGLedger API: change control for AI agents. Agent memory, approvals, audit trail, and notifications: one API, one signed ledger, self-hosted.
Requires an AGLedger Server 2.0 or later. For a 1.x Server, use @agledger/mcp-server@2.11.0, the last release that supports it.
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-serverRelated MCP server: Proofpane
Quick Start
Add to your MCP client configuration (e.g. claude_desktop_config.json):
{
"mcpServers": {
"agledger": {
"command": "agledger-mcp",
"args": ["--api-url", "https://your-agledger-instance"],
"env": { "AGLEDGER_API_KEY": "your-api-key" }
}
}
}The API URL and the API key are both required, unless an OIDC token source
stands in for the key (see
below). The key can also be
passed as --api-key, but the env form keeps it out of the process list. AGLedger is
self-hosted, so there is no default server to call: without --api-url, or
with one that is not an absolute http or https 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, an API URL that is not an http(s) URL), so a launcher can tell a misconfiguration from a
crash.
Authenticating with OIDC instead of an API key
When the operator of your AGLedger Server has registered your identity
provider as a trusted issuer for agents, the MCP server can run with no API key
at all. Give it a source of OIDC tokens instead. It exchanges a token for a
short-lived cert signed by the Server (POST /v1/auth/oidc/cert), presents the
cert as its bearer, and signs each request body with an Ed25519 key that exists
only in its own memory. The Server verifies that signature and seals it into
every chain entry the agent writes (predicate.on_behalf_of.agent_signature).
Nothing is written to disk.
Env var | Description |
| A file holding an OIDC JWT, such as a Kubernetes projected service-account token. Read on every exchange, so a token rotated on disk is picked up. |
| A shell command whose stdout is an OIDC JWT. Run on every exchange. |
| Optional. An assertion of the agent id the token binds to, sent on the exchange. It never chooses the agent: when it names a different one, or the token binds none, the Server refuses the exchange with 403 |
An API key wins when one is set, then the command, then the file.
The token decides which agent the cert binds to, never the MCP server's
configuration. An administrator binds an agent to the token's identity in one
of two ways: PATCH /v1/agents/{id} with oidcIss and oidcSub (the token's
issuer and subject), or a claimMapping of agent_id on the trusted issuer,
which reads the agent id from a claim in the token. An issuer that
auto-provisions agents creates one for an unbound subject instead. A token that
binds no agent is refused, and the Server's recoveryHint says which binding is
missing. A token bound to a federation shadow agent (one listed at
GET /v1/peer-agents) is refused with 403 SHADOW_AGENT_CERT_FORBIDDEN: that
agent authenticates on its own Server.
AGLEDGER_OIDC_TOKEN_FILE=/var/run/secrets/agledger/token \
agledger-mcp --api-url https://your-agledger-instanceIn an MCP client configuration, the token source goes in env:
{
"mcpServers": {
"agledger": {
"command": "agledger-mcp",
"args": ["--api-url", "https://your-agledger-instance"],
"env": { "AGLEDGER_OIDC_TOKEN_FILE": "/var/run/secrets/agledger/token" }
}
}
}The cert is re-exchanged once half its lifetime has passed, and once more if
the Server answers 401 (a revoked cert), after which the request is retried a
single time. A refresh that fails while the current cert is still valid keeps
the current cert and prints one warning on stderr. When the exchange itself is
refused, the tool result carries code: OIDC_EXCHANGE_FAILED, the Server's
status and error body, and its recoveryHint as the result's suggestion.
The Server exchanges a token id (jti) only once, so every exchange needs a
new token. A command runs on every exchange; a file is read on every exchange,
and while it still holds the token already exchanged, the server keeps using
the current cert rather than asking. The kubelet rewrites a projected token at
80% of expirationSeconds, so keep that interval shorter than the trusted
issuer's maxCredentialTtlSeconds, or the cert expires before a new token
appears:
volumes:
- name: agledger-token
projected:
sources:
- serviceAccountToken:
audience: agledger
expirationSeconds: 600
path: tokenActing on behalf of someone
When the agent does work for a person or another party rather than for
itself, the operator can give the server an RFC 8693 delegation token: the
token-exchange result your IdP issues, whose act claim names the agent. The
server sends it as the AGLedger-On-Behalf-Of header on every POST, and the
Server validates it against a trusted issuer registered with
appliesTo: principal and seals it into the chain entry as
predicate.on_behalf_of. The token comes from the process, never from a tool
argument, so the model can neither read nor choose it; agledger_discover
reports only whether a delegation is configured and where it comes from.
Env var | Description |
| A shell command whose stdout is the delegation token. Wins over the file. |
| A file holding the delegation token. |
AGLEDGER_OIDC_TOKEN_FILE=/var/run/secrets/agledger/token \
AGLEDGER_ON_BEHALF_OF_FILE=/var/run/secrets/agledger/on-behalf-of \
agledger-mcp --api-url https://your-agledger-instanceA delegation token is not single use, so it is kept until its exp and read
again after that, or when the Server refuses it with a 401 that names the
delegation (the request is then retried once). With the OIDC cert credential
the delegation is recorded bound: the token's act.sub and actor issuer must
be the cert's own subject and issuer, or the Server answers 403
ACTOR_BINDING_MISMATCH. With an API key there is no validated caller identity
to compare, and it is recorded unbound.
Tools
Tool | Description |
| Returns API health, your identity, available scopes, and a quickstart workflow. Call this first. |
| Make any AGLedger API call (method, path, params). Every POST carries a generated |
| Verify a record audit export offline (COSE_Sign1 envelopes per RFC 9052, hash chain + envelope signatures, Ed25519 or ES256). No network calls. Returns the verifier's result as one JSON text block (the same object as |
Resources
Both are fetched live from the running instance on every read.
Resource | Description |
| 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. |
| 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 typesGET /v1/schemas/{type}: get required fields and examplesPOST /v1/records: create a recordPOST /v1/records/{id}/completions: submit a completion (evidence) when done
Every API error response includes a recoveryHint naming the fix, so an agent can correct itself without a human. Errors raised by the MCP server itself (an argument the tool does not declare, a timeout, a credential failure) carry a code and a suggestion instead.
Configuration
Flag | Env Var | Description |
|
| AGLedger API key. Required unless an OIDC token source is set (see above). |
|
| API base URL of your instance (required). AGLedger is self-hosted, so there is no default; the server refuses to start without it. |
|
| Seconds to wait for each API response (default 30). A positive number up to 2147483; anything else exits 2. |
A call that times out may still have been applied. On a POST, the TIMEOUT error carries the idempotencyKey that was sent: retry with exactly that key and the Server returns the original result instead of creating a second record. Reads and other methods carry no key.
What is AGLedger?
AGLedger is change control for AI agents, delivered as a signed ledger for agentic work. Agents notarize what they intended and what they did, principals approve the work that needs a decision, and every entry is signed, hash-chained and verifiable offline.
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, signed (Ed25519, or ES256 when the operator chooses it), tamper-evident, verifiable offline
Learn more at agledger.ai | API docs
Each self-hosted AGLedger instance serves its OpenAPI document at {AGLEDGER_API_URL}/openapi.json, and an interactive API UI at {AGLEDGER_API_URL}/docs when the operator enables it.
Requirements
Node.js >= 24
A running self-hosted AGLedger API instance, and an API key or a trusted OIDC issuer (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.
Available Tools
3 toolsagledger_apiAGLedger APIADestructive
Make any AGLedger API call. All paths start with /v1/. The API returns nextSteps on every response: follow them. Workflow: 1. GET /v1/schemas, list Record types. 2. GET /v1/schemas/{type}, get required fields and examples. 3. POST /v1/records, create a record. 4. POST /v1/records/{id}/completions, submit evidence when done. If a call fails, read the suggestion field in the error response. For the full API catalog, GET /openapi.json (or read the agledger://openapi resource); for prose orientation, GET /llms.txt (or read the agledger://llms.txt resource). For GET/DELETE, params become query parameters. For POST/PUT/PATCH, params become the JSON body.
Inputs: path (required), method (required), params.
agledger_discoverDiscover AGLedger APIARead-onlyIdempotent
Returns API health, your identity, available scopes, and a quickstart workflow. Call this first. The response tells you who you are and what to do next.
Inputs: no named parameters.
agledger_verifyVerify Audit ExportARead-onlyIdempotent
Verify an AGLedger record audit export offline (format 2.0, COSE_Sign1). Decodes each entry's tagged COSE_Sign1 envelope (RFC 9052), recomputes sha256 over the envelope bytes, walks the hash chain, cross-checks the protected-header chain claim against the row columns, and verifies every envelope signature (Ed25519 or ES256, dispatched from the trusted key material; anything else fails closed). No network calls. For an independent audit, pass publicKeys obtained out of band (GET /v1/verification-keys or /.well-known/scitt-keys) rather than trusting the export's embedded keys; result.keyProvenance reports out-of-band vs embedded key use. On failure, brokenAt pinpoints the first entry that failed and its canonical code (CHAIN_HASH_MISMATCH, CHAIN_LINK_BROKEN, CHAIN_GENESIS_INVALID, CHAIN_COSE_DECODE_FAILED, CHAIN_COSE_HEADER_MISMATCH, CHAIN_PAYLOAD_BINDING_MISMATCH, CHAIN_SIGNATURE_INVALID, CHAIN_SIGNATURE_MISSING_KEY, CHAIN_KEY_POLICY_VIOLATION, CHAIN_ALG_MISMATCH, CHAIN_SIGNING_KEY_DRIFT, CHAIN_UNSUPPORTED_ALGORITHM (this build cannot compute the key's algorithm; upgrade, never a pass), CHAIN_POSITION_GAP, CHAIN_MALFORMED_ENTRY, UNSUPPORTED_FORMAT, CHAIN_EMPTY). Obtain the export via agledger_api with method=GET, path=/v1/records/{id}/audit-export. For the raw COSE_Sign1 stream, use path=/v1/records/{id}/attestation.
Inputs: export, publicKeys, requireKeyId, requireOutOfBandKeys.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct role: discover for orientation, api for arbitrary API calls, and verify for offline audit verification. There is no meaningful overlap in purpose, even though api could technically call discover endpoints; the descriptions direct the agent to use discover first.
All tool names share the consistent agledger_ prefix, but the second parts mix verb forms (discover, verify) with a noun (api). This mixed convention makes the naming pattern less predictable, though still readable.
With only 3 tools, the set is well-scoped. The generic agledger_api tool serves as a catch-all for API operations, while discover and verify fill specialized roles, so each tool earns its place.
The generic agledger_api tool provides access to the full API surface, covering schemas, records, completions, and exports. Discover and verify add orientation and offline verification, leaving no obvious gaps in the tool surface.
Maintenance
Related MCP Connectors
Host any HTTP API as MCP tools with a tamper-evident cross-agent settlement ledger.
Tamper-evident proof creation and verification for AI agents via MCP, A2A, and REST.
Contract-change authorization for AI agents: preflight a change to an API or MCP contract, get a signed decision, and verify the receipt offline. Only a granted change can proceed.
Verifiable execution records for AI agents: signed receipts, tamper-evident archives and portable evidence bundles, exposed via MCP and REST, with paid verify and anchor calls settled over x402.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceTurns any web API into a governed, agent-ready MCP server with lockfile-based approval, fail-closed enforcement, and full audit trail.16 PyPIMIT
- AlicenseBqualityBmaintenanceA governance proxy for AI tools — every MCP/agent tool call is policy-gated, secret-redacted, and written to a hash-chained, offline-verifiable audit trail.13MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to register, send/receive email, store encrypted credentials, emit audit events, and query behavioral trust scores via MCP tools.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables transparent MCP proxying with a hash-chained effect ledger, classifying agent actions by reversibility, enforcing approval gates, and dry-run previews of sessions.MIT