AgentLedger

What the AgentLedger MCP server does

AgentLedger MCP server provides per-agent spend management over a hosted MCP endpoint at https://aiagentscity.com/mcp/. It records entries with an agent ID, payment rail, service, amount, and timestamp. Supported rails are x402, MPP, API keys, and manual entries.

The service groups agents into workspaces and gives each claimed agent its own secret. It can apply monthly budget caps, issue warnings when usage reaches 80% of a limit, and reject a ledger write that would cross the cap. Spending-spike detection produces anomaly alerts, while webhook delivery can send budget warnings, blocks, and anomalies to an HTTP or HTTPS endpoint.

Reports, token usage, alerts, pricing, approval requests, and credential lifecycle operations are available through MCP tools. The service also supports read-only expiring report links and a human-readable report page when the required credentials or share link are supplied.

How it works

A workspace is created either through the /start page or through the x402 billing endpoint. The workspace key claims new agent IDs. Claiming an agent returns an agent secret, which is used for later writes and authenticated reads. Workspace credentials can rotate or revoke an agent secret without deleting the agent’s history.

The MCP endpoint uses streamable HTTP and does not require an authentication handshake to connect. Operations that read or change protected data still require an agent secret or workspace key as an argument or header, depending on the operation. The README states that REST and MCP have no unauthenticated read path.

For provider enforcement, an OpenAI- or Anthropic-compatible client can send requests through the service’s proxy paths. The proxy checks the budget before contacting the provider and forwards the provider key without storing it. A Python wrapper changes the client base URL and adds identity headers without patching the provider SDK.

Setup and configuration

Add the remote endpoint to an MCP client using its streamable-HTTP configuration. The README gives direct setup commands for Claude Code and Codex, and a JSON example for Cursor. Other MCP clients can point to the same URL without custom headers for the initial connection.

Before the first write, obtain a workspace key from /start or the x402 billing route. Claim an agent, save the returned agent secret, and use that secret for subsequent tracking and budget operations. The optional Python client is installed with pip install "aiagentscity-ledger[wrapper]"; its init command can create a workspace, claim an agent, and write a .env file.

Tools and capabilities

AgentLedger MCP server lists these tools:

• ledger_track, ledger_set_budget, and ledger_check_spend for recording and reviewing usage.
• ledger_report, ledger_alerts, and ledger_price for reports, alerts, and token-to-cost pricing.
• ledger_proxy_attach for connecting provider traffic to the enforcement proxy.
• ledger_request_approval, ledger_approvals, and ledger_approval_decide for approval workflows.
• ledger_start, ledger_rotate_secret, and ledger_revoke_secret for workspace and credential operations.
• ledger_api_docs and ledger_examples for API reference and runnable examples.

Pricing can calculate costs from tokens and a model. Unpriced models are refused rather than recorded as zero cost. Provider forwarding is configured through providers.json, with OpenAI, Anthropic, DeepSeek, and Moonshot listed as examples in the README.

Limitations and notes

The free tier supports three agents per workspace. The README describes an x402 payment path for a renewable 24-hour Pro pass with unlimited agents on the wallet’s workspace.

Agent IDs must match the documented length and character restrictions. Reads require an agent secret or workspace key, and secret rotation or revocation is workspace-key-only. The service is hosted rather than presented as a local MCP process in the supplied material, so deployments needing local-only data handling should verify that this architecture fits their requirements.