@agledger/mcp-server
OfficialConnect AI agents to the AGLedger API for signed, auditable change control, with two universal API-pass-through tools and an offline audit verifier.
agledger_discover: Check API health, identity, scopes, and get a quickstart workflow; call first.
agledger_api: Make any AGLedger API call (GET/POST/PUT/PATCH/DELETE) with automatic idempotency keys and self-guided
nextSteps; covers records, completions, schemas, verdicts, etc.agledger_verify: Offline verification of audit exports (COSE_Sign1, hash chain, Ed25519/ES256) with detailed failure codes; supports out-of-band keys and high-assurance key policy enforcement.
Resources: Live
agledger://llms.txtfor orientation andagledger://openapifor exact API specs.Authentication: API key or OIDC token exchange with short-lived certs and optional on-behalf-of delegation tokens.
Agent workflow: Guides through schema listing, record creation, and completion submission with recovery hints on errors.
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-serverdiscover 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.
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-key", "your-api-key",
"--api-url", "https://your-agledger-instance"
]
}
}
}Both flags are required, unless an OIDC token source stands in for the key (see
below). 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.
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 records that signature in the signed chain
entry of every record 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. The agent id to bind the cert to, when the issuer does not map one from the token. |
An API key wins when one is set, then the command, then the file.
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.
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 |
Resources
Both are fetched live from the running instance, so neither can go stale.
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. |
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, 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 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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | API path starting with / (e.g. /v1/records, /v1/schemas, /v1/records/{id}/completions) | |
| method | Yes | HTTP method | |
| params | No | Request parameters as a JSON-encoded string, e.g. '{"type":"notarize-generic-v1","criteria":{"task_description":"..."}}'. For GET/DELETE: becomes query parameters. For POST/PUT/PATCH: becomes the JSON body. Native JSON objects are also accepted for compatibility. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral traits not present in annotations, such as the API's nextSteps mechanism, the suggestion field in errors, and method-specific parameter mapping. These complement the annotations (destructiveHint=true, openWorldHint=true) without contradiction, enriching the agent's understanding of the tool's runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthier than average but well-structured: a one-line purpose, then workflow steps, error guidance, and parameter mapping. Every sentence carries functional weight, though a slight trim of the step-by-step workflow could improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic API caller with no output schema and a complex open-world API, the description is remarkably complete. It tells the agent how to get schemas, required fields, create records, submit completions, recover from errors, and access the full catalog – covering both discovery and execution paths.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already provides descriptions for all three parameters, the description adds practical semantics: path examples, the required /v1/ prefix, a sample JSON parameter string, and the rule that GET/DELETE params become query parameters while POST/PUT/PATCH become the body. This goes beyond the schema's nominal definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Make any AGLedger API call' – a specific verb and resource. It distinguishes itself as the generic API tool, with an explicit workflow for schemas and records, setting it apart from the sibling discover and verify tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a numbered workflow and instructs to follow nextSteps on every response, giving clear context on how to proceed. It also explains error handling and how to access the full API catalog, but does not explicitly state when to choose this tool over agledger_discover or agledger_verify, missing an exclusion clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds useful context by disclosing the response contents (health, identity, scopes, quickstart) and its orientation purpose. This is sufficient for a 0-parameter discovery tool, though it omits response format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the return statement and followed by actionable guidance. Every word contributes; there is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter tool with strong annotations, the description fully covers purpose, output contents, and usage sequencing. Even without an output schema, it clearly communicates what the caller can expect and why this tool should be used first.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is trivially 100%. The description correctly does not attempt to document nonexistent parameters, meeting the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') and clearly enumerates the resources (API health, identity, scopes, quickstart workflow). It also states 'Call this first,' positioning it as an entry point, though it does not explicitly contrast it with sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Call this first' provides explicit contextual guidance for when to invoke the tool, and 'the response tells you what to do next' implies a sequencing role. It does not mention alternatives or exclusion criteria, but the context is clear enough for this simple discovery endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| export | No | The audit export as a JSON-encoded string (the response body from GET /v1/records/{id}/audit-export, JSON.stringify'd). Native JSON objects are also accepted for compatibility. | |
| publicKeys | No | Optional out-of-band signing keys. Accepts any of these as a JSON-encoded string (or a native object/array): a compact map '{"key-1":"MCowBQYDK2VwAyEA..."}' (values are base64 SPKI DER; Ed25519 keys start "MCowBQYDK2Vw", P-256 keys "MFkwEwYHKoZIzj0"), the list shape '[{"keyId":"key-1","publicKey":"MCowBQYDK2VwAyEA..."}]', or the raw GET /v1/verification-keys response envelope ('{"data":[...], ...}'); the .data array is unwrapped automatically, so the agledger_api response can be passed straight through). Merged over any keys embedded in the export. | |
| requireKeyId | No | If set, every entry must reference this keyId. Rejects exports signed by a retired or unexpected key even if cryptographically valid. | |
| requireOutOfBandKeys | No | High-assurance: refuse keys embedded in the export. An entry whose only key is export-embedded fails CHAIN_KEY_POLICY_VIOLATION, forcing verification against keys supplied out of band via publicKeys. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. The description adds significant context: 'No network calls', 'anything else fails closed', 'On failure, brokenAt pinpoints...', and the security recommendation about out-of-band keys. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but information-dense; every sentence serves a purpose. It's front-loaded with the primary action and then systematically covers algorithms, security notes, failure handling, and tool compatibility. Slightly dense as a single paragraph but warranted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description takes on the burden of explaining outcomes. It describes failure output (brokenAt plus canonical codes) and key provenance, but does not explicitly describe a successful result's shape (e.g., whether it returns a boolean or summary), leaving a small gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions, but the tool description adds extra context beyond the schema: e.g., it explains where to fetch publicKeys (GET /v1/verification-keys) and that result.keyProvenance distinguishes key sources, which isn't in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Verify an AGLedger record audit export offline (format 2.0, COSE_Sign1).' It clearly distinguishes itself from siblings by directing the user to agledger_api for obtaining the export and to attestation for raw stream.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use this tool ('For an independent audit, pass publicKeys obtained out of band') and how to obtain the input ('Obtain the export via agledger_api...'), and contrasts with alternatives (raw COSE_Sign1 stream via attestation).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v2.8.0- First observed
agledger_api - First observed
agledger_discover - First observed
agledger_verify
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
Tamper-evident proof creation and verification for AI agents via MCP, A2A, and REST.
Agent knowledge, private memory and coordination. Connect with MCP OAuth or an agent key.
Hash-chained HMAC-signed audit log MCP for A2A (agent-to-agent) calls. Every tool-call, agent-ha...
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
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.MIT
- AlicenseBqualityAmaintenanceA 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 gradedqualityDmaintenanceEnables AI agents to register, send/receive email, store encrypted credentials, emit audit events, and query behavioral trust scores via MCP tools.1 npm5MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to operate through a local, signed boundary that blocks prompt injection and secret leakage, verifies outputs, preserves cross-session memory, and provides offline-verifiable receipts. It also exposes 900+ MCP tools for discoverable agent actions.7MIT