Skip to content
ledgencedocs

Connect an MCP client

Ledgence 0.5.0 includes the optional MCP server in its native bundles and default CLI build. The server connects to your existing Ledgence HTTP API; it does not start infrastructure or require an AI framework.

Install and configure

Section titled “Install and configure”

Use the executable from a native bundle, or build the matching source:

Terminal window
cargo build -p ledgence-cli --locked
./target/debug/ledgence mcp serve \
  --server http://127.0.0.1:8080 \
  --tenant acme \
  --namespace billing

Configure your MCP host to launch that executable with those arguments. The command communicates over stdio; stdout is reserved for protocol messages. Use an absolute executable path in the host configuration. For hosts using mcpServers:

{
  "mcpServers": {
    "ledgence": {
      "command": "/absolute/path/to/ledgence",
      "args": ["mcp", "serve", "--server", "http://127.0.0.1:8080", "--tenant", "acme", "--namespace", "billing"]
    }
  }
}

Add --read-only to expose observation tools only. The API URL and scope are fixed at startup. The API may be remote; no MCP network listener is opened. --no-default-features --features mcp builds this command without telemetry or SQS.

Set --tenant and --namespace to the running instance’s saved binding. The source Compose tutorial uses acme/demo; a new instance with omitted scope uses default/default. The acme/billing values above are examples. A catalog scope mismatch is rejected; it does not switch installations. See One self-hosted instance.

Submit and follow work

Section titled “Submit and follow work”

The server exposes tools for program discovery, task/workflow submission, status/results, task listing, cancellation, external workflow events, and approval inspection. Program discovery requires an installation catalog with matching scope and registered packages; serving the Console frontend is optional.

For ledgence_task_submit, provide:

{
  "program": "invoice-issuer",
  "version": "1.0.0",
  "queue": "billing",
  "data": {"invoice_id": "INV-1042"},
  "idempotency_key": "issue:INV-1042"
}

The response returns an execution ID immediately. Save it and use the matching status/result tool. An observation timeout or disconnected MCP session does not cancel the execution. If submission acceptance is uncertain, resend the exact same key and input; do not create a new key automatically. Only explicit execution cancellation tools request cancellation.

Approval tools inspect the stored effective action. Decisions remain in the human approval interface or CLI; the MCP server cannot approve its own work.

Tool outputs are bounded to 2 MiB without truncation; larger results remain available through the HTTP API. This version provides stdio tools, not Streamable HTTP, model sampling, prompts/resources, package uploads, or MCP Tasks-extension state. See the full tool contract and recovery guide for limits, error semantics, verification and architecture.

Ledgence 0.5 · Versions & downloads