merkl-mcp
Provides tools for interacting with the XRP Ledger through Merkl treasury management, including reading XRP and trust line balances, proposing payments and swaps, and verifying transaction receipts.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
merkl-mcp
Merkl as a tool server. An MCP server — the official mcp SDK, FastMCP —
exposing six tools any agent harness can mount: a treasury that trades
through a Merkl policy it cannot read, receipts it can read back and a verifier
that checks them, the same flow merkl-trader's reference loop runs today,
offered here as tools instead of a loop. Merkl is not in the business of
building agents; it is the thing any agent's money goes through.
The tools
tool | input | returns |
| — | address, network, balances (XRP and each trust line), policy version, the signer's health line, whether a proposal is pending with a person |
|
| this agent's recent receipts in words: outcome, what was asked for, the rule that refused it if any, when |
|
|
|
|
| same three shapes as |
| — |
|
|
| the SDK verifier's verdict in words, run locally on that receipt in the agent's store: whether anything was contradicted, whether every check ran, what was not checked |
why becomes the proposal's reasoning note (200 characters). A tool never
raises to the model: every failure is a result with error in words. Only
one proposal may be open at a time — a second propose_* call while one is
waiting returns waiting_for_a_person without touching the signer.
Five verbs for money and evidence (get_treasury, propose_payment,
propose_swap, pending_approval, read_receipts) plus verify_receipt.
Market data (order books, prices) is not served here: it comes from the
harness or any XRPL/market MCP server mounted beside this one, for example
xrpl-mcp-server for the book and the CoinGecko MCP for reference prices.
propose_payment and propose_swap also accept session_id, session_action_count
and depends_on. A harness that opened a Merkl session passes them so the receipt
joins that session (the receipt's session_locator and one payments action in
it); the model never supplies them. They are no-ops without a session_id.
Related MCP server: CasperAgentKit
Configuration
Everything this server needs is the five-file agent bundle merkl treasury init writes (trader.toml, agent-ed25519.pem, wallet.json, and the
optional relay/notary secret files), read from $MERKL_AGENT_DIR (default
/agent), plus trader.toml's [agent], [treasury], [rail], [signer]
and [notary] tables. There is no [market], [model], [loop] or
[bill] section — this process has no trading loop, no model and no compute
bill of its own; every "which asset, which size, why" question arrives as a
tool argument instead.
The agent's receipts are read from and written to receipts/ in the bundle
directory (override with $MERKL_RECEIPT_DIR), so that directory must be
writable. An optional [market] table in trader.toml (base, quote_code,
quote_issuer) is named back to the agent in get_treasury's market field;
assets lists each balance as {code, issuer, balance}. With optional [bill] and
[loop].home tables (or $MERKL_TRADER_HOME), get_treasury also returns
compute_bill: {owed, currency: "XRP", due_day, due_now, operator}: the
harness journal's cost_usd since the last settled payment to the operator, in XRP at
CoinGecko's public price (cached 10 minutes); owed is null when no price is available.
The one proposal a person may be deciding on
lives under $MERKL_MCP_STATE (default /var/lib/merkl-mcp) — writable,
unlike the read-only bundle — so an escalation survives a restart without
re-preparing a transaction the policy key never signed.
Install
uv venv .venv
uv pip install -p .venv/bin/python -e ".[dev]"Running it
merkl-mcp # stdio — what every mount below actually uses
merkl-mcp --http :8765 # streamable HTTP instead, on every interfacedocker run --rm -i \
-v "$PWD/merkl-agent:/agent" -v merkl-mcp:/var/lib/merkl-mcp \
ghcr.io/ramcav/merkl-mcp:0.1.0Mounting it
Four harnesses, one server. All four launch the same merkl-mcp process
over stdio and tell it where the agent bundle lives via MERKL_AGENT_DIR;
nothing else needs to cross the boundary; the bundle's secrets are for
merkl-mcp to read off disk itself.
Claude Code
claude mcp add merkl -e MERKL_AGENT_DIR=/path/to/merkl-agent -- merkl-mcpClaude Desktop — claude_desktop_config.json:
{
"mcpServers": {
"merkl": {
"command": "merkl-mcp",
"env": { "MERKL_AGENT_DIR": "/path/to/merkl-agent" }
}
}
}OpenAI Agents SDK — the shape merkl-trader's own harness
(merkl_trader/harness/loop.py) mounts it with:
from agents.mcp import MCPServerStdio
server = MCPServerStdio(
params={"command": "merkl-mcp", "env": {"MERKL_AGENT_DIR": "/path/to/merkl-agent"}},
name="merkl-mcp",
client_session_timeout_seconds=30,
)Mount a market server beside it for the book and prices; Merkl does not provide one.
Hermes — the same mcpServers convention as Claude Desktop:
{
"mcpServers": {
"merkl": {
"command": "merkl-mcp",
"args": [],
"env": { "MERKL_AGENT_DIR": "/path/to/merkl-agent" }
}
}
}The container's box
The image runs as uid 10002 and /agent arrives read-only. If a bundle file
was prepared with different ownership, this server reports a one-line error
naming the file and the fix:
chown -R 10002:10002 merkl-agent/Testing
pytest -q --timeout 60
ruff check merkl_mcp tests
ruff format --check merkl_mcp testsAgainst merkl.demo.rig's real signer, real encrypted keystore and the
SDK's in-memory rail — only the balance reader is faked, because the
in-memory rail has no JSON-RPC node to ask (see merkl_mcp/ledger.py).
See also
merkl-sdk— the policy layer this server is built on.merkl-trader— the reference trading agent; itsfeat/harnessbranch mounts this server over the OpenAI Agents SDK.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Agent-native MCP for governed commerce, x402 payments, paid capabilities, and verifiable receipts.
Policy-gated MCP treasury for AI agents — x402 subscribe, 50+ tools, multi-chain.
Crypto transaction firewall and risk tools for MCP agents.
An agent wallet over MCP: balances, and sends, swaps and earn moves its owner approves.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for agent treasury management. Creates yield-bearing vaults, manages USDC deposits, and runs programmable time-based payment streams between agents.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with the Casper blockchain through MCP tools for reading node state, inspecting blocks, querying global state, and evaluating treasury policies. Includes a Treasury Guard reference agent that autonomously enforces DeFi treasury policies on Casper Testnet.MIT

vantic-mcpofficial
AlicenseNot gradedqualityDmaintenanceEnables MCP hosts to verify agent spending mandates and receipts, providing stateless tools for authorization, chain verification, credential verification, and DID resolution.Apache 2.0- FlicenseNot gradedqualityBmaintenanceEnables autonomous agents and MCP-compatible clients to enforce policy-approved actions using risk tiers, reversible checkpoints, and token approval bounds.7-