MCP Server

The AGLedger MCP server gives any MCP-compatible AI agent access to your AGLedger instance. It exposes two tools — one for discovery, one for API calls — and the agent handles the rest.

Why it matters

Agents operating inside your organization need accountability the same way human employees do. The MCP server is the simplest integration path: install it, point it at your AGLedger instance, and every MCP-compatible agent (Claude, Cursor, Windsurf, Cline, or any custom agent) can create mandates, submit receipts, and query the audit trail.

The server is intentionally thin. It does not interpret, filter, or transform API responses. Your agents get the full API surface through a single tool, and the API itself guides them through each workflow via nextSteps on every response.

Prerequisites

Before setting up the MCP server, you need:

  1. A running AGLedger instance — See the Installation guide if you haven't deployed yet
  2. An agent API key — Created during self-hosted onboarding (step 6)

If you don't have an agent key yet, create one using your platform key:

curl -X POST "http://10.0.1.50:3001/v1/admin/api-keys" \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerId": "your-agent-uuid",
    "ownerType": "agent",
    "role": "agent",
    "label": "procurement-agent-mcp",
    "scopeProfile": "agent-full"
  }'

The response includes the key once — save it. It starts with ach_age_. See Scope Profiles for options beyond agent-full.

Key and agent metadata for audit trails

Every API key and agent account carries metadata that appears in audit trails and reporting. Setting these fields at creation time makes it straightforward to trace activity back to a specific team, environment, or purpose.

On the API key (set at key creation):

On the agent account (set at agent creation via POST /v1/admin/agents):

A descriptive label on the key and orgUnit on the agent pay for themselves the first time you need to investigate a mandate or trace activity across agents.

Install

npm install -g @agledger/mcp-server

Requires Node.js 22 or later.

Connect to your AGLedger instance

The MCP server needs two things: the agent API key from the prerequisite step and the URL of your AGLedger instance.

# Using an IP address (common in air-gapped or DNS-free environments)
agledger-mcp --api-key ach_age_your_key --api-url http://10.0.1.50:3001

# Using a hostname
agledger-mcp --api-key ach_age_your_key --api-url https://agledger.internal:3001

You can also set these as environment variables:

export AGLEDGER_API_KEY=ach_age_your_key
export AGLEDGER_API_URL=http://10.0.1.50:3001
agledger-mcp

Network requirements

The MCP server runs on the same machine as your agent. It connects outbound to your AGLedger API server. Ensure the agent host can reach the API host on the configured port (default: 3001). No inbound ports are required on the agent host.

Agent Host                         API Server
+-----------------+                +-------------------+
| AI Agent        |                | AGLedger API      |
|   ↕ stdio       |                | (port 3001)       |
| MCP Server      | --TCP:3001-->  |                   |
+-----------------+                +-------------------+

Configure your agent

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "agledger": {
      "command": "agledger-mcp",
      "args": ["--api-key", "ach_age_your_key", "--api-url", "http://10.0.1.50:3001"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "agledger": {
      "command": "agledger-mcp",
      "args": ["--api-key", "ach_age_your_key", "--api-url", "http://10.0.1.50:3001"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agledger": {
      "command": "agledger-mcp",
      "args": ["--api-key", "ach_age_your_key", "--api-url", "http://10.0.1.50:3001"]
    }
  }
}

Claude Code

Add to .claude/settings.json in your project:

{
  "mcpServers": {
    "agledger": {
      "command": "agledger-mcp",
      "args": ["--api-key", "ach_age_your_key", "--api-url", "http://10.0.1.50:3001"]
    }
  }
}

Any MCP client

The server communicates via stdio. Pass agledger-mcp as the command with --api-key and --api-url arguments. No special transport configuration is needed.

How agents use it

The server exposes exactly two tools:

agledger_discover

The agent calls this first. It returns:

agledger_api

The agent uses this for every subsequent API call. It accepts a method, path, and parameters:

agledger_api({ method: "GET", path: "/v1/schemas" })
agledger_api({ method: "POST", path: "/v1/mandates", params: { ... } })

The API returns nextSteps on every response, telling the agent what to do next. On errors, a suggestion field provides specific recovery guidance. The agent self-corrects without human intervention.

Typical agent workflow

  1. Agent calls agledger_discover — learns who it is and what to do
  2. Agent calls GET /v1/schemas — sees available contract types
  3. Agent calls GET /v1/schemas/ACH-DATA-v1 — gets required fields for a data processing mandate
  4. Agent calls POST /v1/mandates — creates the mandate with criteria
  5. Agent does its work
  6. Agent calls POST /v1/mandates/{id}/receipts — submits evidence of completion

The agent discovers this workflow from the tools themselves. You do not need to prompt or instruct the agent on how to use AGLedger.

API key scopes

The API key you provide determines what the agent can do. AGLedger provides scope profiles designed for common use cases:

Use the narrowest profile that covers your agent's needs. See Scope Profiles for the full list, including enterprise profiles for admin scripts and CI/CD.

Customization

Custom contract types

If your organization has registered custom contract types via the Schema Development Toolkit, they appear automatically when agents call GET /v1/schemas. No MCP server configuration is needed — the server passes through whatever your API returns.

Tool descriptions

The MCP server registers its tools with descriptions that guide agent behavior. These descriptions are compiled into the server binary. If you need to customize the workflow guidance for your organization (for example, to reference specific contract types or internal procedures), you can:

  1. Fork the @agledger/mcp-server package
  2. Edit the description strings in src/server.ts
  3. Build and deploy your customized version

This is useful when your agents consistently work with a specific contract type and you want to skip the schema discovery step.

Timeout configuration

The default API timeout is 30 seconds. For environments with high-latency network paths between the agent host and API server, you can adjust this by modifying the ApiClient constructor in the source.

Troubleshooting

Agent calls discover but then stops

The agent received identity information but no workflow guidance. Verify you are running MCP server v2.0.2 or later, which includes the quickstart workflow in the discover response.

Agent gets 404 errors

All API routes use the /v1/ prefix. If the agent is calling /mandates instead of /v1/mandates, check that you are running MCP server v2.0.2 or later, which includes correct path examples in the tool descriptions.

Connection refused

The MCP server cannot reach your AGLedger API. Verify:

Authentication errors

The API key is invalid or expired. Verify:

Built-in API documentation

Your AGLedger instance serves machine-readable API documentation that agents can access through the MCP server:

These paths are included in the agledger_discover response. Agents fetch them when they need detailed API information beyond what nextSteps provides.