x402-hedera-mcp

Give any AI agent a wallet it can't overspend and an auditor it can't fool — over MCP.

Tally's metered x402 upto payments and on-chain audit, exposed as Model Context Protocol tools. Drop it into Claude Desktop, Cursor, the Hedera Agent Kit, or any MCP-capable runtime, and your agent can pay for what it uses on Hedera — and prove the bill was honest — without you writing any payment code.

Three tools:

| Tool | What it does | Needs a key? | | --- | --- | --- | | tally_pay | Pay a metered upto invoice: sign a spending ceiling off-chain (no gas, no transaction from the agent), settle the actual metered amount, then audit the receipt. | Yes — BUYER_ID + BUYER_KEY | | tally_audit_settlement | Audit any seller's settlement against the chain — signatures, charge == units × signed unit price, under the ceiling, paid the named recipient. | No — public data only | | tally_seller_reputation | Score a seller's honesty by replaying its HCS receipts topic: clean/total settlements, honesty ratio, on-chain volume, disputes. | No — public data only |

The two audit tools read nothing but the public Hedera Mirror Node and HCS. No API key, no account, no cooperation from the seller. An agent can check who it's about to pay, and verify what it paid, entirely on its own.

Why this exists

An autonomous agent that pays for things needs two guarantees before it's safe to give it a wallet: it can't be drained (it must never spend more than authorised) and it can't be fleeced (an overcharge must be detectable). upto gives the first — the agent signs a ceiling and the contract enforces it. Tally's receipts give the second — every charge is signed, anchored to Hedera, and recomputable by anyone. This server hands both to your agent as callable tools.

Install & run

# no install — run the published server directly
npx -y x402-hedera-mcp

# or from this repo
npm -w x402-hedera-mcp run build
node packages/x402-hedera-mcp/dist/index.js

It speaks MCP over stdio. tally_audit_settlement and tally_seller_reputation work with zero configuration. tally_pay activates when the buyer environment is set (below).

Configure it in an agent

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "tally": {
      "command": "npx",
      "args": ["-y", "x402-hedera-mcp"],
      "env": {
        "HEDERA_NETWORK": "hedera:testnet",
        "BUYER_ID": "0.0.xxxxxxx",
        "BUYER_KEY": "your-ecdsa-private-key-hex"
      }
    }
  }
}

Cursor — ~/.cursor/mcp.json (same shape)

{
  "mcpServers": {
    "tally": { "command": "npx", "args": ["-y", "x402-hedera-mcp"], "env": { "HEDERA_NETWORK": "hedera:testnet" } }
  }
}

(Omit BUYER_ID/BUYER_KEY to expose only the two keyless audit tools — a safe read-only setup.)

Hedera Agent Kit / any @modelcontextprotocol/sdk client

The Hedera Agent Kit and other MCP-capable runtimes connect to stdio MCP servers the same way — point them at the x402-hedera-mcp command with the same env. Programmatically:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({ command: 'npx', args: ['-y', 'x402-hedera-mcp'], env: process.env });
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

await client.callTool({ name: 'tally_seller_reputation', arguments: { topicId: '0.0.9557142' } });
await client.callTool({ name: 'tally_pay', arguments: { resourceUrl: 'http://localhost:4021/v1/complete', prompt: 'summarise x402' } });

Environment

| Variable | Used by | Notes | | --- | --- | --- | | BUYER_ID | tally_pay | Hedera account id of the buyer — an ECDSA account with an EVM alias. | | BUYER_KEY | tally_pay | The buyer's ECDSA private key (hex). Never leaves the machine; it only signs authorisations. | | HEDERA_NETWORK | all | hedera:testnet (default) or hedera:mainnet. Overridable per-call via the network argument on the audit tools. |

tally_pay also needs a reachable x402 upto resource (the resourceUrl argument) served by a facilitator that supports the scheme — e.g. the Tally seller + facilitator in this repo.

Tools

tally_pay

{ resourceUrl: string, prompt: string } → pays the invoice at resourceUrl, returns the completion, the metered charge, the settlement transaction (with a HashScan link), and the audit verdict. The agent signs the ceiling and sends no transaction of its own; a facilitator settles.

tally_audit_settlement

{ topicId: string, transactionId?: string, network?: string } → audits one settlement (the most recent on the topic, or the one named by transactionId) and returns every check plus a clean/dishonest verdict.

tally_seller_reputation

{ topicId: string, disputesTopicId?: string, network?: string, limit?: number } → returns each seller's honesty ratio, clean/total settlements, on-chain volume, and disputes.

License

Apache-2.0. Part of Tally.