Agents and MCP
Stellar Assist is the agent side of Stellar Split. It runs in your own Hermes or OpenClaw assistant and you talk to it on Telegram. It reaches the API through an MCP server that holds its credential, so the model never sees a token or a key.
The MCP server and its tools are built. Paying through an agent (ledgerly_settle) is built and runs only when a signer file is configured, on Testnet, at most 25 per call. Approvals and per-agent policy screens are planned: the Assist screens in the web app run on labelled sample data until their API exists.
Stellar Assist
- Lists your groups, reads balances and records expenses from a chat message.
- Proposes a settlement: who to pay and how much, without paying.
- When its operator gives it a signer, pays within the server caps from its own Testnet account, on your behalf once you link it.
The MCP server
Code in mcp/. Node 22 or newer, ES modules, dependencies @modelcontextprotocol/sdk, @stellar/stellar-sdk and zod. Tool names keep the project's earlier name, ledgerly_*.
Run with Node
git clone https://github.com/Michella-stack/Stellar-Split.git
cd Stellar-Split/mcp
npm ci && npm test
# stdio (default), for a local MCP client
LEDGERLY_API_URL=https://stellar-split-sooty.vercel.app LEDGERLY_TOKEN=<agent token> npm start
# streamable HTTP on 127.0.0.1:8787/mcp
LEDGERLY_API_URL=https://stellar-split-sooty.vercel.app LEDGERLY_TOKEN=<agent token> \
MCP_TRANSPORT=http MCP_AUTH_TOKEN=<random> npm start
Run with Docker
mcp/Dockerfile builds the image. mcp/compose.example.yml runs one MCP container per agent: non-root, read-only filesystem, cap_drop: ALL, no-new-privileges, 256 MB, on an internal network shared only with that agent. Never publish its port.
docker build -t ledgerly-mcp:local mcp/
cp mcp/compose.example.yml ~/stellar-agents/mcp-hermes/docker-compose.yml
# .env from scripts/agent-mcp/new-agent-token.sh (writes the tokens, prints only the AGENT_TOKENS line)
docker network create --internal mcp-hermes
AGENT=hermes MCP_IMAGE=ledgerly-mcp:local SIGNER_FILE=/path/to/key docker compose up -d
Environment variables
| Variable | Required | Meaning |
|---|---|---|
LEDGERLY_API_URL | Yes | API origin. Must be https unless it is localhost |
LEDGERLY_TOKEN | Yes | The agent token. Stays in this process, never returned to the model |
MCP_TRANSPORT | No | stdio (default) or http |
MCP_HTTP_HOST, MCP_HTTP_PORT | No | Default 127.0.0.1 and 8787. Endpoint /mcp, POST only |
MCP_AUTH_TOKEN | If the host is not loopback | Bearer token the agent sends to the MCP server |
LEDGERLY_SIGNER_FILE | No | Path to a file with the agent's Testnet secret key. Read once at start. Unset means no ledgerly_settle |
LEDGERLY_HORIZON_URL | No | Default https://horizon-testnet.stellar.org |
Transport
stdio, or stateless streamable HTTP: one server and transport per request, nothing kept between calls. HTTP clients must send Accept: application/json, text/event-stream (otherwise the SDK answers 406). Wrong or missing bearer: 401. A method other than POST: 405. Body over 1 MB: 400.
Tools
| Tool | Inputs | Output | Spends money |
|---|---|---|---|
ledgerly_list_groups | none | The GET /v1/groups body | No (read only) |
ledgerly_get_balances | group_id | { balances: [{ memberId, displayName, address, kind, net }] } | No (read only) |
ledgerly_create_expense | group_id, payer, amount, description (1 to 200), split, idempotency_key? | { expense } | No |
ledgerly_propose_settlement | group_id, to, amount | Dry-run { intent }; reserves nothing | No (read only) |
ledgerly_settle | group_id, to, amount, on_behalf_of?, idempotency_key? | Transaction hash, explorer link, status | Yes. Only with a signer file |
split is { rule: "equal", participants: [id] } or { rule: "exact", shares: [{ member, amount }] }, 1 to 50 distinct members. Ids match ^[A-Za-z0-9_-]{1,64}$. Amounts are positive decimals with up to 12 integer digits and 7 decimals. Exact shares are summed with integers before any call. Text that looks like a secret key is refused. Without idempotency_key, the server makes a random one, so asking twice creates two expenses.
Errors come back as a tool error with { status, error: { code, message } }, passed through from the API.
Client configuration
Hermes
# ~/.hermes/config.yaml
mcp_servers:
ledgerly:
url: "http://ledgerly-mcp:8787/mcp"
headers:
Authorization: "Bearer <MCP_AUTH_TOKEN>"
trust: untrusted
tools:
include: [ledgerly_list_groups, ledgerly_get_balances, ledgerly_create_expense, ledgerly_propose_settlement]
trust: untrusted makes tools without readOnlyHint ask before they run. Check the key names against your pinned Hermes version.
OpenClaw
Register the server under mcp.servers.ledgerly with url, transport: "streamable-http" (set it, or OpenClaw may fall back to SSE) and headers, then probe it:
openclaw mcp doctor ledgerly --probe
Use toolFilter.exclude to hide ledgerly_settle from an agent that should not pay.
Claude Desktop, Cursor and other stdio clients
The repository does not ship configs for these. Any MCP client that starts a stdio server can run it the same way. A generic entry looks like this; adapt it to your client's config format:
{
"mcpServers": {
"ledgerly": {
"command": "node",
"args": [
"/path/to/Stellar-Split/mcp/src/main.js"
],
"env": {
"LEDGERLY_API_URL": "https://stellar-split-sooty.vercel.app",
"LEDGERLY_TOKEN": "<agent token>"
}
}
}
}
A desktop config file stores the agent token in plain text on your machine. Use a Testnet agent with small funds, and leave LEDGERLY_SIGNER_FILE unset unless you mean the client to pay.
Spend policy
| Rule | Value | Enforced |
|---|---|---|
| Per payment | 25 | API (AGENT_CAP_PER_PAYMENT) and the MCP server (hard ceiling) |
| Rolling 24 hours | 50 | API (AGENT_CAP_PER_DAY) |
| Rolling 30 days | 200 | API (AGENT_CAP_PER_MONTH) |
| Ask me first above a threshold Planned | Proposed 5 | Not built: no approvals route |
| Per-agent limits set by the owner Planned | Not built: caps are fixed defaults |
Caps count over all the agent's groups. Reserved, settled, expired and in-review intents count, because they may have moved money. A refused reservation is cancelled at once. Every denial is logged as agent_spend_denied. People are not capped. An agent can only pay members of groups it belongs to.
Approval flow Planned
The design: above the ask-me-first threshold the API holds the payment as a pending approval, you approve or reject it in the app, and it expires after an hour. An agent can never approve its own request, because approving needs a person's session and agent tokens get 403 on person-only routes. None of this is in the API yet: there is no /v1/approvals route, and the MCP server has no approval tool.
Linking an agent to you
- The operator registers the agent's address and token hash in
AGENT_TOKENS. - You call
POST /v1/agents/link/challengewith{ agentAddress }and sign the message in Freighter. - You send
POST /v1/agents/linkwith the message and signature. - The agent can now reserve intents with
onBehalfOfset to your member id: the debt stays yours, the agent pays from its own account, and its caps count. - Revoke at any time with
DELETE /v1/me/agents/:address.
How ledgerly_settle pays
- Validates input, then reserves an intent through the API. The model never supplies payment terms.
- Asks the x402-style route for terms and expects
402. - Exactly one
acceptsentry must match the intent and the pinned config: schemeexact, networkstellar:testnet, a pinned USDC or EURC issuer,payTo, amount, intent id and API host. Any difference aborts with nothing signed. - Signs one classic payment with the intent memo as
MEMO_HASHand time bounds up to the intent expiry, and submits it to Horizon Testnet. Each intent id is signed at most once per process. - Retries with
PAYMENT-SIGNATURE. The API verifies it on Horizon and records the settlement.
Agent wallets
- Each agent has its own funded Testnet account with a trustline. Its key stays on the host, outside the agent container.
- The key file is mounted read-only into the MCP container only (
/run/secrets/signer, mode 0400), read once at start, and never put in an environment variable, a log or tool output. - The agent container gets no key mount, no Docker socket and no host paths.
- Funding is by hand: Friendbot for XLM, Circle's faucet for test USDC. There is no agent-callable funding tool.
x402 with a facilitator Planned
Today's x402 flow is x402-style and self-verified: the API answers 402, the agent sends a classic Stellar payment, and the API checks it on Horizon. There is no external facilitator, no Soroban authorization entry, no @x402/* package, and the contract's record_x402_settlement is not called. Those are on the roadmap.
Prompt injection protections
Tool output contains text written by people (expense descriptions, names), and it reaches the model. Treat it as untrusted. The defences do not rely on the model behaving:
- The API enforces membership and spend caps for the agent token, whatever the model asks.
- The agent token and the signer key stay in the MCP process. The model never sees them.
- The MCP server checks payment terms against the reserved intent and pinned config before it signs.
- Secret-key-shaped text is refused by the MCP inputs and by the API.
- Write tools prompt in Hermes (
trust: untrusted) and OpenClaw (approval modeprompt). That prompt is a convenience, not a security boundary: an agent with shell, file or HTTP tools can readMCP_AUTH_TOKENfrom its own config. Turn off agent tools you do not need. - Known gap:
ledgerly_create_expensecan name any member as payer, so an injected instruction can record a false expense. It cannot move money.