stellar-copilot-mcp

MCP server for Stellar. Ask an AI assistant what an account holds, why a transaction failed, or what a Soroban contract does — and get an answer in plain language. Optionally, propose payments the user approves in their own wallet.

Holds no keys. Signs nothing. Submits nothing. Reads use public chain data. Transactions are built unsigned and handed to a page the user controls; signing happens in Freighter and nowhere else.

---

Tools

Tool	Answers
explain_account	"What do I hold?" · "Why can't I spend my whole balance?" · "Is my trustline set up?"
diagnose_transaction	"Why did this fail?" — decodes transaction and operation result codes into causes and fixes, and recovers Soroban contract error codes
explain_contract	"What can this contract do?" — reads a deployed contract's published interface

Running the HTTP transport adds three more:

Tool	Purpose
start_pairing	Returns a link the user opens in the browser where Freighter lives
get_pairing_status	Whether the wallet connected, and how an approval turned out
propose_payment	Builds an unsigned payment and sends it to the user's approval page

The stdio binary exposes only the three read tools. Pairing needs a server to host the approval page and hold session state, which stdio has neither of.

Install

Requires Node 20+.

npm install && npm run build

Claude Code

claude mcp add stellar-copilot -- node /absolute/path/to/stellar-copilot-mcp/dist/index.js

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "stellar-copilot": {
      "command": "node",
      "args": ["/absolute/path/to/stellar-copilot-mcp/dist/index.js"],
      "env": { "STELLAR_NETWORK": "testnet" }
    }
  }
}

Cursor and other local clients take the same command; see their connector docs.

Remote clients (ChatGPT, Gemini)

Remote clients connect over a URL rather than spawning a process, so run the HTTP transport:

npm run start:http

Serves MCP at http://127.0.0.1:3000/mcp and a health check at /health. Point your client at the /mcp URL.

To use it from Claude, ChatGPT, or Gemini you need a public HTTPS URL — those clients cannot reach localhost. A Dockerfile and fly.toml are included. See DEPLOY.md.

Configuration

Variable	Default	Notes
STELLAR_NETWORK	testnet	testnet or public
STELLAR_HORIZON_URL	network default	Override for a private Horizon
STELLAR_RPC_URL	testnet default; empty on mainnet	Required on public — see below

HTTP transport only:

Variable	Default	Notes
PORT	3000	Listen port
HOST	127.0.0.1	Bind address. Keep it on loopback unless it is behind a reverse proxy.
MCP_PATH	/mcp	Endpoint path
MCP_ALLOWED_HOSTS	localhost variants	Comma-separated. Required when deployed under a real hostname, or requests are rejected with 403.
MCP_ALLOWED_ORIGINS	unset	Comma-separated browser origins, if any

On mainnet you must set STELLAR_RPC_URL. SDF does not operate a public mainnet Soroban RPC endpoint, so there is no sensible default. Horizon-backed tools (explain_account, diagnose_transaction) work on mainnet without it; explain_contract needs it and will tell you so rather than failing at startup.

Try it

npm run inspect   # MCP Inspector

Or drive it directly:

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node dist/index.js

Development

npm run typecheck   # tsc --noEmit
npm run dev         # tsc --watch
npm run build       # emit to dist/

Two constraints to respect when adding code

stdout is the JSON-RPC channel. Never write to it. All logging goes to stderr — a stray console.log corrupts the protocol stream, and the failure looks like a client bug.

The HTTP transport is stateless. No session IDs, no shared state — a fresh server per request. Every tool is a pure read, so there is nothing to remember between calls, and stateless means no session table to leak, expire, or scale. It also means POST is the only meaningful method: there is no stream to open and no session to delete.

DNS rebinding protection is on by default. Without it, any web page the user visits could POST to a server bound on localhost and drive its tools from the browser. Deploying under a real hostname means adding it to MCP_ALLOWED_HOSTS.

Keep this server read-only. No key material, no signing, no submission. Transaction building and signing belong behind an independent simulation-and-approval step in a separate deployable (see ../TECHNICAL-SPEC.md). The boundary is structural, not a policy note.

Decoding contract errors

Contract-defined codes (Error(Contract, #1205)) mean whatever that contract's #[contracterror] enum says, so they need a protocol table. Pass a protocol hint:

diagnose_transaction(hash: "...", protocol: "blend-v2-pool")

Known tables: blend-v1-pool, blend-v2-pool, soroswap-pair — see src/lib/contractErrorTables.ts.

Tables are keyed by protocol, not contract address, because Blend pools are permissionless: every pool is a separate deployment sharing one error enum, so an address-keyed registry would mean enumerating every pool that will ever exist.

KNOWN_CONTRACTS maps verified addresses to protocols and is intentionally empty. An address goes in only once confirmed against a published deployment list — a wrong entry would attach a confident wrong explanation to someone's real failed transaction. Every table must cite the source and date it was read from; a test enforces this.

Adding a failure explanation

src/lib/resultCodes.ts maps XDR result-code names to a { meaning, fix } pair. Add the code, write the explanation for someone who has never read the Stellar docs, and say what to do about it.

Contract-defined codes are not in the result XDR, and they are not recoverable from the historical record either: Horizon 27 returns no transaction meta at all, and public Soroban RPC nodes leave diagnosticEvents empty. The server recovers them by re-simulating the call, and says so in its output — simulation runs against current ledger state, so it is evidence rather than proof of the original error.

Status

Verified against live Stellar testnet on 30 July 2026: clean typecheck under strict + noUncheckedIndexedAccess, working MCP handshake, correct reserve math on a Friendbot-funded account, and correct diagnosis of a real failed Soroban contract call.

62 unit tests (including the HTTP transport and the approval page end to end) and 9 live integration tests pass. The pairing flow, independent decoding, and injection blocking are verified in a real browser.

Not yet verified: Freighter signing itself. It is a browser extension, so signTransaction and the submit path need a machine with Freighter installed. Known gap: KNOWN_CONTRACTS is empty, so contract errors need an explicit protocol hint until verified deployment addresses are added.

Proposing transactions

Only over the HTTP transport:

PUBLIC_BASE_URL=https://your-host npm run start:http

The flow:

1. start_pairing returns a link. The user opens it where Freighter is installed.
2. The page connects the wallet and reports the address back.
3. propose_payment builds an unsigned transaction and queues it for the page.
4. The page decodes the XDR itself and shows what it actually does.
5. The user signs in Freighter. The page submits.
6. get_pairing_status reports the outcome.

Why the page decodes it again

The assistant's description of a transaction is treated as an untrusted claim, never as truth. If a prompt injection made the model build a malicious transaction, the model's description of that transaction would be malicious too — so the only thing that catches it is comparing the description against independently decoded reality.

When they disagree, the page shows the mismatch and disables the approve button. A warning a user can click straight past is not a control.

For the same reason, no tool returns a decoded preview to the model. If it could read the decode, it could misreport it, and the user would be approving the model's account of the transaction rather than the transaction. A test asserts no such tool exists.

PUBLIC_BASE_URL must be an origin the user's browser can reach; it is what pairing links point at. Sessions are in-memory, expire after 30 minutes idle, and hold no key material.

Privacy

The server runs locally, stores nothing, and handles only public blockchain identifiers — never keys or credentials. It queries public Stellar infrastructure (Horizon, Soroban RPC), both of which you can repoint via environment variables. Full policy: PRIVACY.md.

Licence

Apache-2.0