Stellar Testnet only. No real money moves. What this means

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.

Status

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

VariableRequiredMeaning
LEDGERLY_API_URLYesAPI origin. Must be https unless it is localhost
LEDGERLY_TOKENYesThe agent token. Stays in this process, never returned to the model
MCP_TRANSPORTNostdio (default) or http
MCP_HTTP_HOST, MCP_HTTP_PORTNoDefault 127.0.0.1 and 8787. Endpoint /mcp, POST only
MCP_AUTH_TOKENIf the host is not loopbackBearer token the agent sends to the MCP server
LEDGERLY_SIGNER_FILENoPath to a file with the agent's Testnet secret key. Read once at start. Unset means no ledgerly_settle
LEDGERLY_HORIZON_URLNoDefault 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

ToolInputsOutputSpends money
ledgerly_list_groupsnoneThe GET /v1/groups bodyNo (read only)
ledgerly_get_balancesgroup_id{ balances: [{ memberId, displayName, address, kind, net }] }No (read only)
ledgerly_create_expensegroup_id, payer, amount, description (1 to 200), split, idempotency_key?{ expense }No
ledgerly_propose_settlementgroup_id, to, amountDry-run { intent }; reserves nothingNo (read only)
ledgerly_settlegroup_id, to, amount, on_behalf_of?, idempotency_key?Transaction hash, explorer link, statusYes. 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>"
      }
    }
  }
}
Tokens in client config

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

RuleValueEnforced
Per payment25API (AGENT_CAP_PER_PAYMENT) and the MCP server (hard ceiling)
Rolling 24 hours50API (AGENT_CAP_PER_DAY)
Rolling 30 days200API (AGENT_CAP_PER_MONTH)
Ask me first above a threshold PlannedProposed 5Not built: no approvals route
Per-agent limits set by the owner PlannedNot 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.

  1. The operator registers the agent's address and token hash in AGENT_TOKENS.
  2. You call POST /v1/agents/link/challenge with { agentAddress } and sign the message in Freighter.
  3. You send POST /v1/agents/link with the message and signature.
  4. The agent can now reserve intents with onBehalfOf set to your member id: the debt stays yours, the agent pays from its own account, and its caps count.
  5. Revoke at any time with DELETE /v1/me/agents/:address.

How ledgerly_settle pays

  1. Validates input, then reserves an intent through the API. The model never supplies payment terms.
  2. Asks the x402-style route for terms and expects 402.
  3. Exactly one accepts entry must match the intent and the pinned config: scheme exact, network stellar:testnet, a pinned USDC or EURC issuer, payTo, amount, intent id and API host. Any difference aborts with nothing signed.
  4. Signs one classic payment with the intent memo as MEMO_HASH and time bounds up to the intent expiry, and submits it to Horizon Testnet. Each intent id is signed at most once per process.
  5. 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 mode prompt). That prompt is a convenience, not a security boundary: an agent with shell, file or HTTP tools can read MCP_AUTH_TOKEN from its own config. Turn off agent tools you do not need.
  • Known gap: ledgerly_create_expense can name any member as payer, so an injected instruction can record a false expense. It cannot move money.
Last updated 26 October 2026Edit this page on GitHub