convez.ai
MCP ServerIntegração & APIsAvançado
akporh

ZeroKey MCP — Proxy de Ferramentas Premium sem API Keys

akporh/zerokey-mcp

Pay-per-call para ferramentas dev via Hedera, sem API keys expostas.

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que proxeia ferramentas premium (análise de código, dados Hedera, leitura de tópicos) com cobrança por uso em HBAR via protocolo x402. Elimina necessidade de API keys expostas — agentes pagam por chamada de forma transparente, com reembolsos automáticos em caso de falha e suporte a allowances pré-aprovadas.

Instalação

$npx convez-ai akporh/zerokey-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
1
Saúde
28%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Análise de segurança de código Python sob demanda
  • Consultas de dados Hedera (contas, tokens, transações) com pagamento por chamada
  • Auditoria imutável de todas as operações via HCS topic
  • Agentes autônomos com limite de gasto pré-aprovado via allowances

Veredito

Solução inovadora e bem arquitetada para faturamento M2M trustless via blockchain. Ideal para construtores que buscam remover gerência de API keys e implementar pagamento por uso auditável — exige familiaridade com Hedera e x402 protocol.

README

A tradução para o português deste README ainda está na fila.

ZeroKey — Install Once. Pay Per Call. Zero API Keys.

An autonomous Machine-to-Machine (M2M) billing proxy that allows Model Context Protocol (MCP) clients (Claude Desktop, Cursor, custom agents) to discover and execute premium server-side tools on-demand — paid per call in HBAR via the x402 protocol on Hedera.

No API registrations. No subscriptions. No API keys exposed to the agent.


How it works

Claude calls a tool via MCP
          ↓
ZeroKey issues x402 payment challenge
          ↓
Agent pays in HBAR using Hedera Agent Kit
          ↓
Payment verified on Mirror Node
          ↓
Tool executes — findings + Hashscan links returned (~15 seconds)
          ↓
Every event logged immutably to HCS audit topic

Payment is transparent to Claude. No 402 errors surface to the user.


Tools

ToolWhat it doesPricePayment mode
scan_codePython security analysis (Pyflakes + Bandit)0.50 HBARx402 receipt
get_account_infoHedera account balance + metadata0.10 HBARx402 receipt
lookup_tokenHTS token metadata0.10 HBARx402 receipt
read_hcs_topicRead public HCS topic messages0.10 HBARx402 receipt
get_transactionHedera transaction details0.10 HBARx402 receipt
scan_code_allowanceSame as scan_code, paid via pre-approved allowance0.10 HBARallowance pull
demo_failAlways fails after payment — demonstrates refund guardrail0.10 HBARx402 receipt

Payment guardrails

Automatic refunds — if a tool fails after payment is received, ZeroKey automatically dispatches a full HBAR refund to the agent's account. No manual intervention required.

Spending allowances — agents can pre-approve a spending limit via Hedera's native allowance mechanism. The proxy pulls payment within the approved limit, no 402 challenge needed. The agent's private key never leaves the client.

Human-in-the-loop approval — set ZEROKEY_REQUIRE_APPROVAL=true to enable an approval dialog before each payment via MCP elicitation. The agent pauses and asks the user to approve before broadcasting. Fails open gracefully on non-interactive clients. Note: MCP elicitation support varies by Claude Desktop session — the dialog appears when the client's elicitation API is active and may not show on every call. When it does not appear, payment proceeds automatically and all guardrails remain in effect.


Audit trail

Every event is written to HCS topic 0.0.9120320 — sequenced, tamper-proof, publicly verifiable:

hashscan.io/testnet/topic/0.0.9120320

Events logged: 402_issued → payment_verified → tool_executed (or tool_failed + refund_sent)

Every tool response includes direct Hashscan links for the payment transaction, payer wallet, and audit topic.


Install in Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hedera-proxy": {
      "command": "/full/path/to/mcp-server/.venv/bin/python3.12",
      "args": ["-m", "mcp_server"],
      "env": {
        "HEDERA_ACCOUNT_ID": "your-testnet-account",
        "HEDERA_PRIVATE_KEY": "your-ecdsa-private-key",
        "HEDERA_NETWORK": "testnet",
        "ZEROKEY_PROXY_URL": "http://localhost:8000",
        "ZEROKEY_REQUIRE_APPROVAL": "true",
        "PYTHONPATH": "/full/path/to/mcp-server"
      }
    }
  }
}

Note: cwd is ignored by Claude Desktop. Use PYTHONPATH to point at the mcp-server directory so Python can find the mcp_server module.

Restart Claude Desktop. Confirm hedera-proxy shows as running under Settings → Developer → MCP Servers.


Run the proxy

cd mcp-server
.venv/bin/python3.12 -m uvicorn src.main:app --port 8000

You will see the startup banner listing all 7 tools and the proxy URL.


Architecture

Claude Desktop
  └── mcp_server.py  (MCP stdio, spawned by Claude Desktop)
        ├── 7 tools — scan_code, get_account_info, lookup_token,
        │             read_hcs_topic, get_transaction, scan_code_allowance, demo_fail
        ├── x402 payment flow: 402 challenge → HBAR broadcast → receipt polling
        ├── Allowance flow: direct pull via pre-approved on-chain allowance
        ├── HITL via MCP elicitation (ZEROKEY_REQUIRE_APPROVAL=true)
        └── Hashscan links appended to every tool response

src/main.py  (FastAPI proxy, port 8000)
  └── x402 middleware — issues challenges, validates receipts, dispatches refunds
  └── HCS audit writer — every event logged to topic 0.0.9120320
  └── Tool registry — price + endpoint mapping

Accounts (Hedera testnet)

RoleAccount
Server (receives payment)0.0.9082590
Agent (pays for tools)0.0.9089637
HCS audit topic0.0.9120320

Review panel

A companion dashboard built alongside ZeroKey to support development and review:

review-panel-app.vercel.app

TabWhat it showsRequires local proxy?
Architecture docsSystem design, flow diagrams, data contractsNo
Kanban / RoadmapSprint history and delivery progressNo
RegistryLive tool registry with pricesYes (port 8000)
Simulationx402 payment flow simulationYes (port 8000)

Architecture docs and project history are fully accessible on Vercel. Registry and simulation require the proxy running locally on port 8000.


Judge setup

  1. cd mcp-server && pip install -r requirements.txt
  2. Copy .env.example → .env, fill in server account credentials
  3. Start proxy: .venv/bin/python3.12 -m uvicorn src.main:app --port 8000
  4. Update claude_desktop_config.json with your full paths and agent account credentials
  5. Restart Claude Desktop → run the demo prompts in DEMO.md

Stack

  • Python 3.12 + FastAPI + Hedera Agent Kit v4
  • MCP protocol (stdio transport)
  • x402 payment protocol
  • Hedera testnet — Mirror Node + HCS + CryptoTransfer + Allowance

Bounty

Entry for Hedera AI Agent Bounty — Week 3: MCP or x402 Agent. Demo (full 5-act): youtu.be/SDhiGFgNMj0 Demo (original): youtu.be/TYJhflMr0tA

Ver o original no GitHub

Bom para

Relacionados