Pion.

A Model Context Protocol server for Pi Network

unofficial community project · not affiliated with Pi Network

Abstract

Pion connects AI agents — Claude, Cursor, and any MCP-compatible client — to the Pi Network blockchain. Out of the box it exposes read-only tools for wallet balances, payment history, transaction verification, and identity: no API keys, no wallet secrets, nothing that can move value. The chain reads run against either Pi network, and every result names which one it came from. App-to-User payments are a different matter: they exist behind a four-condition arming gate, are testnet-only because Pi restricts them there, and are deliberately off by default. It is a step toward agents that can transact on Pi safely, with humans holding the leash.

Fig. 1 — In particle physics, the pion is the π meson, and pion decays are studied in searches for MCPs (millicharged particles). A π particle producing MCPs: we found the name irresistible.

1.Tools

A default install can look, verify, and reason about on-chain state — it cannot spend, sign, or hold anything. The spend tool is not merely disabled when unarmed: it is never registered, so an agent cannot see that the capability exists.

Tool	What the agent gets
`get_wallet_balance`	Pi and token balances for any wallet address — mainnet or testnet
`get_account_payments`	Payment history for an account
`query_transaction`	Details and verification of a specific transaction
`verify_user`	Validates a Pi access token, returning uid and username
`send_payment`	App-to-User payment — off unless armed, testnet only

Arming send_payment takes four separate acts: an explicit switch, a mandatory per-payment ceiling, both credentials, and Pi Testnet as the selected network. Selecting mainnet does not merely discourage payments — it makes arming impossible, and the server does not advertise a spending tool at all. Holding the credentials is deliberately not sufficient. The realistic failure mode is not a stolen key — it is an agent talked into spending by instructions sitting in data it just read, and the ceiling is what makes that bounded rather than fatal.

2.Quickstart

Add Pion to your MCP client's configuration — for Claude Desktop, that's claude_desktop_config.json:

{
  "mcpServers": {
    "pion": {
      "command": "npx",
      "args": ["-y", "pion-mcp"]
    }
  }
}

Restart the client and ask your agent for a testnet wallet balance. The read tools need no keys or configuration; the payment tool is optional and off by default.

3.Status

v0.1 — read-only Horizon tools, verified against live testnet
v0.2 — verify_user identity checks via the Platform API
v0.3 — App-to-User payments proven end to end on testnet: created, signed, submitted, and confirmed on-chain independently of the tool's own report
v0.4 — mainnet reads. Horizon URL and network passphrase verified against the live nodes rather than assumed from the naming pattern — the mainnet passphrase is Pi Network, not the Pi Mainnet the pattern predicts. Payments remain testnet-only and unarmable elsewhere
Hardening send_payment before recommending it to anyone else — its failure paths were exercised deliberately, and the drill found a defect that would have lost funds
The rest of Tier C as MCP tools: payment status, incomplete-payment recovery, and the User-to-App backend half
Later — agent allowance delegation: humans authorize, agents spend within bounds

send_payment is honestly experimental. The success path is verified; so are the two stranded-payment branches, which were induced on purpose rather than waited for. What that exercise found — that a Pi payment record cannot distinguish "never sent" from "sent but unreported" — is written up with the primary evidence in FINDINGS.md, alongside three other undocumented behaviours the build turned up.

4.References

Pion source repository — Apache-2.0, contributions welcome.
pion-mcp on npm
Model Context Protocol — the open standard Pion implements.
Pi Platform documentation