Polarka Agent MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Polarka Agent
A wallet for TrueNorth (NORTH) that a program can use: a command line, a Python library, and a server for agents that speak the Model Context Protocol (MCP). The keys stay on the machine it runs on. What its addresses hold it asks a wallet server with the Northbound API (github.com/nova9/northbound).
State: 0.1.1, an early version. It was written with an AI model under its author's direction. An
independent AI reviewer read it and found faults, the serious ones of which are mended (REVIEW.md); no
human security expert has read it. On 17 November 2026 it made its first payments on the real network: two
small payments went into blocks, and its owner's limits refused what they should (NO_LIMITS, OVER_LIMIT,
OVER_DAY). That is all the real use it has had. Do not put into it what you cannot lose. It is an independent community project, not a product of the TrueNorth developers or of
the Northbound project.
What it is for
A program that has a processor and no bank account can earn NORTH by mining and can be paid in it. This wallet lets such a program hold coins and pay small amounts by itself, within bounds that a person sets and that the tools given to the program cannot change.
Related MCP server: paean-pay-mcp
How a program is kept within bounds
Without a file
limits.jsonin the wallet's folder the wallet pays nothing. Its owner writes that file by hand:{"per_payment_north": "5", "per_day_north": "20"}, and if wanted"allow": [addresses]and"fee_rate". No command and no tool of the MCP server writes or changes it.Every transaction is written into
journal.jsonlbefore anything leaves the machine. Lines are only added.The MCP server has no tool that shows the recovery words, changes the limits or forgets a payment.
These bounds hold against a program that reaches the wallet through the MCP server only. A program that can run commands or write files as the same user can change
limits.json, move the journal away or read the words; against that the wallet does nothing. Give an agent the MCP server, not a shell in that account.A payment counts into its day whatever became of it; only the owner's
forgettakes one out. A payment that another one replaced therefore counts twice for a day.What a wallet server says in words is not passed on to the program: a refusal comes as one of a few fixed words and an error as its HTTP status.
The recovery words are in wallet.json, readable by its owner only (mode 600; the program refuses to work
with a file that others can read). Whoever can read that file can spend. This is a wallet for small amounts
on a machine its owner controls.
Paying, and a server that says no
The rules are those of the Polarka Wallet for Android, which an independent reviewer looked at.
Whoever was shown a signed transaction can keep it and pass it on later, whatever they answered. So a
payment that the server refused (kept) or that got lost (unknown) is not forgotten. The next payment is
built on one of its coins, and only one of the two can ever be in a block. The same payment asked for again
(same coins, same outputs) is the same transaction and is simply shown to the server once more. While the
server shows none of the coins of such a payment, the wallet pays nothing at all, until its owner has looked
at the wallet through another server or a node and forgets the payment by hand (forget).
A wallet server sees the wallet's addresses together and the machine's internet address. It can show a false
balance or hold a payment back. It can stop the wallet until its owner acts (by refusing a payment and then
hiding its coins), and it can keep one command waiting for a long time by answering slowly. It cannot take
coins. A program is not shown the server's own words: why a node refused a payment comes as one of a few
fixed words (FEE_TOO_LOW, INPUTS_GONE, OTHER, ...), an error as its HTTP status, and a receiver in the
history only if it has the shape of an address. The words themselves appear at the command line alone,
under server_said_untrusted, for the owner.
Installing
pip install polarka-agentThat gives the command polarka-agent, which is the same as python3 -m polarka_agent. It needs Python 3.9
or later on Linux or macOS and nothing besides; it does not run on Windows. The package on PyPI is built from
this repository at the tag of its version; after 0.1.1 the workflow in .github/workflows/release.yml builds
and uploads it, and prints the SHA-256 of the files it made.
Commands
python3 -m polarka_agent --dir FOLDER new --chain regtest --server http://127.0.0.1:PORT
python3 -m polarka_agent --dir FOLDER address | balance | history | payments | limits
python3 -m polarka_agent --dir FOLDER pay ADDRESS 1.5 [--memo TEXT] [--dry-run]
python3 -m polarka_agent --dir FOLDER pay-many FILE.json
python3 -m polarka_agent --dir FOLDER received ADDRESS | wait ADDRESS 1.5
python3 -m polarka_agent --dir FOLDER stamp FILE | stamp --sha256 HEX
python3 -m polarka_agent --dir FOLDER forget ID
python3 -m polarka_agent --dir FOLDER mcpEvery command prints one JSON object. Amounts are NORTH, written as text. new --chain main takes the public
server of the Northbound project (https://api.northboundwallet.org) unless another is named; that server is
not run by this project. new shows the 12 or 24 words once; --words-file brings a wallet back.
A stamp writes POLARKA\x01 and a SHA-256 into an output that carries data. The chain is young and its hash
rate is small: a stamp shows an order of events, it is not proof for a court.
For an agent: start python3 -m polarka_agent --dir FOLDER mcp as an MCP server over standard input and
output. Its tools are north_balance, north_address, north_received, north_wait, north_pay,
north_stamp, north_payments, north_history and north_limits.
A first coin: the faucet
A program that has no coin can ask a faucet for one. It does a small piece of work first (hashing, a few seconds of one processor), so that asking a thousand times costs a thousand times as much.
python3 -m polarka_agent --dir FOLDER faucet https://ADDRESS-OF-A-FAUCETasks for a little NORTH to a fresh address of the wallet. There is no public faucet yet; when there is one, its address will be on polarka.org.
Anybody can run one: faucet-serve --amount 2 hands out 2 NORTH to an address once a day from the wallet in
FOLDER. What it may give in a day is that wallet's limits.json, nothing else, so a faucet is this wallet
under its own bounds. It keeps the addresses it paid (faucet.jsonl) and no internet addresses on disk; it
asks for no name and no e-mail. It is meant to stand behind a web server that provides HTTPS
(--trust-proxy). The faucet is new: nobody independent has read it, and it has never run in public.
Something to pay for: postage
Whoever runs a web service and wants to keep robots from wearing it out makes them burn processor time for nothing today. With postage the caller pays a little NORTH instead, and the one who runs the service gets it.
python3 -m polarka_agent --dir FOLDER postage-serve --upstream 127.0.0.1:9000 --price 0.01 --calls 100 --free 20stands before the service on port 9000. A caller without postage gets 402 and what to do, as JSON: ask for
a quote (POST /_postage/quote), pay the price to the address it names, and send the token in the header
X-Postage. Every quote has an address for itself for half an hour, so a payment is told apart without
anybody proving anything; an address that was not paid serves the next asker. --free lets one source make
some calls a day without postage.
Postage is counted in calls. It is not a balance, it is not given back, and the gate never pays from its
wallet, so the gate holds nobody's coins. Whoever runs a service for payment has the duties of one who does
(saying who they are, among others); the gate is a tool and takes none of them away. It is new: nobody
independent has read it, and it has never run in public. There is no asker's command for it yet: a program
pays the quoted address with pay and sends the token itself.
Code and tests
Python 3.9 or later, standard library only. polarka_agent/keys.py and tx.py hold the keys, addresses, the
signature hash and signing; they come from the cold address tool
(github.com/severka-monitor/truenorth-cold-address) and are checked against its published P2QRH test vectors.
server.py is the client for a wallet server, wallet.py the wallet, cli.py and mcp.py the two faces,
faucet.py the faucet and its asker, postage.py the postage gate.
TN_BIN=/path/to/bin python3 -B -m unittest discover -s tests -t .79 tests. Those in test_wallet.py and test_cli_mcp.py run against the official truenorthd on regtest
and a stand-in for a Northbound server (tests/standin, copied from the Polarka Wallet's repository); they
are skipped without the node programs. No test touches a real network.
tests/faults.py is a test of the tests: it puts one deliberate fault at a time into a copy of the code
(a limit that is not applied, a day that does not count the payment being made, and so on) and expects the
tests to fail. It first runs the copy as it stands, and counts a fault as caught only when tests ran and failed. Ten faults
in the owner's rules. It covers those rules only, not the keys, the signing or the client of the server.
What is missing
A review by a person. An independent AI reviewer read version 0.1.0.dev0 and found two serious faults (a server that lies about a block could lift the day's limit; after two hundred addresses the wallet sent change where it did not look). Both are mended here, with tests. Its other findings are listed in
REVIEW.mdwith what was done about each.More than two hundred addresses of a kind: beyond that the wallet hands out no new address and reuses its last change key.
More than a first try on the real network.
A way to replace a payment that was handed over and waits for a block without end.
A node of one's own in place of a wallet server.
A history that is exact for a wallet with more than a hundred addresses.
Checking a stamp without trusting a server or a node.
Licence
MIT, see LICENSE. There is no warranty.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
An agent wallet over MCP: balances, and sends, swaps and earn moves its owner approves.
Agent-to-agent marketplace with escrow-protected trades via MCP tools.
Agent wallet & Pulse Market MCP — register, hire with escrow, earn USDC. 20 tools. MIT.
Agent MCP: 65 tools — 5-chain verification, risk, prediction & crypto trends, 17 web tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage Bitcoin micropayments, service offers, and escrow contracts through MCP tools, without requiring a Lightning node.12 npmMIT

paean-pay-mcpofficial
AlicenseNot gradedqualityDmaintenanceEnables AI agents to send and receive USDC stablecoin payments on Base and Solana blockchains through MCP tools for wallet operations, balance checks, payment requests, and transfers.23 npm7MIT- AlicenseNot gradedqualityAmaintenanceEnables AI agents to manage API keys and child keys with budgets and spending caps, set plans and model routing, handle wallet payments and top-ups, and verify signed receipts through MCP tools.265 npm2MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to propose policy-gated treasury payments and swaps, check pending human approvals, read transaction receipts, and locally verify their integrity through MCP tools.MIT