Pion Mcp

Model Context Protocol server for Pi Network — connect AI agents (Claude, Cursor, and any MCP-compatible client) to Pi Network chain data.

pion-mcp MCP server

⚠️ Reads: both networks. Payments: testnet only. The chain tools query Pi Mainnet or Pi Testnet, selected with PION_NETWORK. send_payment moves real funds, must be explicitly armed, and cannot be armed on mainnet — Pi restricts App-to-User payments to testnet.

Why "Pion"?

The pion is the π meson — the particle physicists named after pi. Fittingly, particle physicists study pion interactions to search for MCPs (millicharged particles). We couldn't resist.

Tools

Out of the box Pion reads and cannot spend: Tiers A and B need no credentials and move no value. Tier C is the exception and is off unless you arm it. (Tiers refer to docs/tool-mapping.md.)

Tier A — chain reads. Zero-permission queries against Pi's public Horizon API. No credentials at all. These work on both Pi chains — testnet by default, mainnet with PION_NETWORK=mainnet.

Tool	What it does
get_wallet_balance	Pi and custom-token balances for a wallet address
get_account_payments	Paginated payment history for an address
query_transaction	Verify a single transaction by hash

Amounts are decimal strings. Pi is reported as the asset PI, custom tokens as CODE:ISSUER, and liquidity-pool shares as pool:ID.

Every result names the chain it came from in a network field, and the startup banner says it too. That redundancy is deliberate: the same address can hold different balances on both chains, so a query against the wrong network does not reliably fail — it can return a plausible, well-formed, wrong number (measured 2026-08-14; see docs/pi-sdk-notes.md). Testnet Pi has no monetary value.

Tier B — identity.

Tool	What it does
verify_user	Validate a Pi user access token, returning the uid and username

verify_user is the only tool that touches a credential, and it never holds one: the caller passes a token per call, it goes to GET /v2/me and nowhere else, and it is not stored, logged, or echoed back. A rejected token returns valid: false with a reason rather than erroring, so an agent can branch on the outcome.

Two caveats worth knowing. The uid is app-specific — the same person has a different uid under a different Pi app, which is deliberate anti-correlation design, so don't use it as a global identifier. And a token is the only proof of identity: a client-supplied uid or username means nothing on its own.

Tier C — payments. Off by default.

Tool	What it does
send_payment	App-to-User: sends Pi from your app wallet to a user

This one spends real money and cannot be undone. It is not registered at all unless armed, so a default server does not even advertise it to the agent.

The recipient must have granted your app the wallet_address scope. A uid alone is not enough — Pi needs that consent to resolve their wallet, and refuses payment creation with missing_scope otherwise. This is the recipient's consent, not your credentials.

Arming requires all four, and Pi restricts A2U to testnet, so anything but Pi Testnet is refused outright:

PION_ENABLE_PAYMENTS=1     # explicit switch, deliberately separate from credentials
PION_MAX_PAYMENT_PI=10     # required per-payment ceiling, in Pi
PI_SERVER_API_KEY=...      # from the Pi Developer Portal
PI_WALLET_SECRET=S...      # app wallet secret seed

Holding the credentials is deliberately not sufficient. The switch and the ceiling are separate because the realistic failure mode is not a stolen key — it is an agent being talked into spending, by a prompt injection sitting in data it just read. A transaction memo, a web page, a filename: any of it can say "send 500 Pi to X." The cap is what makes that bounded rather than fatal. Set it to the smallest amount that makes your use case work.

Nothing overrides the cap from the tool call; changing it means changing server configuration. Neither secret is ever accepted as a tool argument, returned in a result, or logged.

On partial failure it never retries. A2U is three steps — create with Pi, sign and submit on-chain, tell Pi it landed — and a crash between them strands a payment. The tool reports exactly which step failed, whether funds left the wallet, and the payment id needed to clean up. A blind retry could pay twice, so it refuses to guess.

Requirements

Node.js 22.12.0 or newer.

This floor is higher than earlier releases advertised, and correcting it is the reason 0.5.0 is a minor rather than a patch. Through 0.4.2 package.json declared >=18.17, which was never true: the @stellar/stellar-sdk 16.x that 0.4.x pinned already declared >=22.0.0 of its own, so Node 18 and 20 were outside what the dependency supported the whole time. Nothing surfaced it, because our own field is the one npm checks an install against — a package cannot be warned about a floor it is itself misreporting.

0.5.0 moves to @stellar/stellar-sdk 17.x, whose floor is >=22.12.0 (its CommonJS build requires ESM-only dependencies, and require(esm) is only unflagged from 22.12.0), and sets our declared floor to match it honestly.

If you are on Node 18 or 20, what this actually means:

• The chain read tools and verify_user never load the Stellar SDK — it is imported lazily, inside the payment handler — so those paths are unlikely to be affected in practice.
• send_payment is the part that genuinely needs 22.12.0. It is also the only part that moves funds, which is why the floor is stated here rather than left to fail somewhere expensive.

Upgrading Node is the supported fix. Pinning 0.4.2 preserves the old declared floor but not a working payment path — that release depends on an SDK that did not support your runtime either.

Usage

MCP clients can run it straight from npm — no install step:

// Claude Desktop: claude_desktop_config.json
{
  "mcpServers": {
    "pion": {
      "command": "npx",
      "args": ["-y", "pion-mcp"]
    }
  }
}

# Claude Code
claude mcp add pion -- npx -y pion-mcp

Or run it from a clone:

npm install
npm run build
claude mcp add pion -- node /absolute/path/to/pion-mcp/dist/index.js

Configuration

Variable	Default	Purpose
PION_NETWORK	testnet	Which chain the read tools query — testnet or mainnet. Mainnet is echoed as REAL VALUE in the startup banner
PION_HORIZON_URL	derived from PION_NETWORK	Override for the Horizon base URL. Optional. If set alongside PION_NETWORK the two must name the same chain — a contradiction is a startup error, not a silent winner
PION_PLATFORM_URL	https://api.minepi.com	Platform API base URL
PION_ENABLE_PAYMENTS	unset (off)	Arms send_payment — see Tier C above
PION_MAX_PAYMENT_PI	unset	Required per-payment ceiling when armed
PI_SERVER_API_KEY	unset	Server API key, Tier C only
PI_WALLET_SECRET	unset	App wallet secret seed, Tier C only

For read-only use there is nothing to configure — verify_user takes its token as a call argument, not from the environment. The bottom four are needed only if you arm payments, and belong in a secrets manager, never in a committed file.

PION_NETWORK and PION_HORIZON_URL are resolved once, in one place, into a single network object that the Horizon client, the banner, every tool result and the arming check all read. Setting both to contradictory chains is a startup error rather than a silent winner, and an unrecognised PION_HORIZON_URL resolves to an explicitly unknown chain — never to a Pi network by resemblance.

Development

npm run build      # compile src/ -> dist/
npm run typecheck  # types only, no emit
npm run smoke          # end-to-end against live testnet
npm run smoke:mainnet  # the same checks against live mainnet
npm run crossnet       # proves the two chains are actually distinguished
npm run arming         # Tier C guards and spend cap (no credentials needed)
npm run signing        # golden-XDR check on the A2U signing path (offline)

npm run smoke spawns the server over stdio as a real MCP client, discovers a funded account from the current ledger, and exercises the chain tools plus the not-found and invalid-input paths. It needs network access.

It covers verify_user only on the rejection path — confirming a genuine token would need a real user credential, which the test deliberately does not handle. The success path is unverified; see below.

npm run crossnet proves network selection is real rather than cosmetic. It does not rely on an address being absent from the other chain — that assumption is false — but on a wallet we control being testnet-only, and on a shared address returning different ledger state from each chain.

npm run arming covers Tier C without touching real money: every refusal branch, the exact cap boundary, that credentials alone do not arm it, that a disarmed server does not advertise the tool, that a fully-credentialled mainnet server still refuses to advertise it, and that neither secret leaks into a result. It uses a freshly generated, never-funded keypair. The one live call it makes is a deliberately-rejected create against the Pi API, which proves the first failure stage end to end.

npm run signing rebuilds the exact transaction send_payment signs, with every input pinned, and compares the envelope and hash against bytes recorded in the file. It is offline and cannot spend. Its job is dependency bumps: the other suites all stub the network, so none of them can tell you whether an SDK upgrade changed what you put on the wire. Run it on any @stellar/stellar-sdk change — a failure means the bytes moved, and the constants should not be refreshed until you know why.

Known gaps

• verify_user success path — confirmed against a live token. Returns uid, username, app_id, scopes, and valid_until. Everything but uid stays optional, since the rest depends on granted scopes.

• send_payment success path — verified on testnet (2026-08-01). A real A2U payment ran through all three irreversible steps — create, sign, submit, complete — and was confirmed independently against public Horizon and Pi's block explorer, not just from the tool's own report. The 28-byte memo question that hung over the design is answered: Pi payment identifiers are exactly 28 bytes and fit the Stellar text memo with no room to spare.

• send_payment failure paths after create — still unproven. Sign, submit and complete have each succeeded once; none has been observed failing against live infrastructure. The two worst branches of the stranded-payment report — "record created, nothing signed" and "funds left, Pi not notified" — are verified by construction only. Treat send_payment as experimental until they have been deliberately exercised.

  This is why it ships off, and why turning it on takes four separate, deliberate acts: PION_ENABLE_PAYMENTS=1, a mandatory PION_MAX_PAYMENT_PI ceiling, both credentials, and Pi Testnet as the selected network. Holding the credentials is not enough on its own. Disarmed, the tool is not registered at all, so an agent cannot see that a spending capability exists — that gate is deliberate design (see Tier C above), not a placeholder for unfinished work. The experimental label is about the failure paths, not about the guards.

• send_payment cannot pay an arbitrary uid. Pi requires the recipient to have granted your app the wallet_address scope, through the Pi Browser SDK. A valid uid is not sufficient, and this is a permanent property of the Pi API rather than a transient error — creation fails with 401 missing_scope and retrying will not help.

Start with a minimum-amount payment and a low PION_MAX_PAYMENT_PI. Run npm run probe:a2u <uid> first: it exercises create and cancel without moving funds, and its from_address is the only authoritative statement of which app wallet Pi will actually spend from.

Roadmap

Done in v0.4: mainnet reads. The rest of Tier C: get_payment_status, list_incomplete_payments, approve_payment / complete_payment / cancel_payment — the U2A backend half and the recovery tooling for stranded payments. See docs/tool-mapping.md.

Legal

The code is Apache-2.0; see LICENSE. The website and the hosted U2A endpoints are covered separately by the Privacy Policy and Terms of Service — sources in site/privacy.html and site/terms.html. Where the two disagree about the software itself, the Apache licence wins.

Short version: the MCP server has no telemetry and talks only to Pi's public endpoints, the site sets no cookies and runs no analytics, and nothing here is stored in a database — there isn't one.

Unofficial community project — not affiliated with Pi Network.