convez.ai
MCP ServerIntegração & APIsIntermediário
dimitrilaouanis-tech

Onyx Paid MCP — Framework de Servidores MCP com Micropagamentos

dimitrilaouanis-tech/onyx-mcp

MCP pago em 5 linhas — charge agentes de IA direto em USDC

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework Python para criar servidores MCP pagos que cobram agentes de IA por chamada via USDC na Base, sem chaves de API ou fluxo de signup. Inclui 33 ferramentas prontas: primitivas on-chain (Base/Solana), OCR de captcha, automação de browser e utilitários web, com liquidação instantânea via protocolo x402.

Instalação

$npx convez-ai dimitrilaouanis-tech/onyx-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
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
—
Issues abertas
3
Contribuidores
1

Casos de uso

  • Monetizar ferramentas MCP com custo operacional real (OCR, scraping, LLM)
  • Integrar primitivas blockchain (Base/Solana) em agentes Claude com cobrança por uso
  • Automatizar browser e validações (captcha, email, IP geo) com pagamento por chamada

Veredito

Framework técnico sólido que resolve um problema real: monetizar MCP tools com custo marginal. Implementação limpa do padrão x402, mas exige compreensão de wallets EVM e modelo de pagamento por chamada para máximo valor.

README

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

onyx-paid-mcp — build a paid MCP server in 5 lines

PyPI License x402

USDC settlement on Base. No Stripe, no API keys, no signup flow. Charge AI agents per call directly through the protocol they already speak.

from onyx_paid_mcp import App

app = App(
    name="hello-paid-mcp",
    receive_address="0xYourBaseWallet",
    network="base",   # or "base-sepolia" for free testnet
)

@app.tool(
    name="echo",
    price_usdc="0.001",
    description="Returns whatever you send.",
    input_schema={"type": "object", "properties": {"text": {"type": "string"}}, "required": ["text"]},
)
def echo(text: str) -> dict:
    return {"echoed": text}

if __name__ == "__main__":
    app.serve(port=8080)

That's it. pip install onyx-paid-mcp, point at any wallet address, decorate any function. You now have:

  • Streamable HTTP MCP at /mcp/ — installable in Claude Desktop, Cursor, Cline, mcp-use
  • REST endpoint at /v1/<tool> — for non-MCP agents
  • HTTP 402 gate that charges your wallet per call in USDC
  • Bazaar-discoverable manifest at /.well-known/x402.json — Coinbase auto-indexes
  • Free introspection at /, /manifest, /health

Why

Every MCP today is free-as-in-unmetered. That breaks at scale for any tool with real per-call expense (OCR, scraping infra, LLM passes, anything backed by a physical resource). onyx-paid-mcp lets you charge directly through the agent's wallet — the same way a paywall works in a browser, except the wallet signs an EIP-3009 USDC authorization instead of pulling out a credit card.

Install

pip install onyx-paid-mcp

Generate a Base wallet (gen_wallet.py in this repo, or any EVM wallet generator), set it as ONYX_RECEIVE, run your tool. Agents pay you in USDC the second they call.

Reference implementation

onyx-actions — the live server using this framework. Paid tools across Base on-chain primitives, captcha OCR, URL text extraction, DNS, WHOIS, email validation, IP geo, FX, browser automation, and a workflow chainer. All shipped as one-file modules in tools_pkg/.

ToolPrice
onyx_base_tx_explainer$0.05
onyx_base_tx_simulator$0.10
onyx_base_token_risk_scan$0.25
onyx_base_tx_decode$0.002
onyx_token_metadata$0.001
onyx_solana_tx_explainer$0.05
onyx_solana_token_metadata$0.0008
onyx_solana_token_risk_scan$0.25
onyx_solana_jupiter_quote$0.001
onyx_solana_wallet_activity$0.002
onyx_ens_resolve$0.0008
onyx_solve_captcha$0.003
onyx_url_text$0.001
onyx_url_unshorten$0.0005
onyx_whois$0.001
onyx_dns_lookup$0.0005
onyx_email_validate$0.0008
onyx_ip_geolocate$0.0008
onyx_fx_convert$0.0008
onyx_password_strength$0.0003
onyx_user_agent_parse$0.0003
onyx_browser_* (6 tools)$0.002–$0.008
onyx_agent_workflow$0.020

Smithery listing: https://smithery.ai/servers/dimitrilaouanis/onyx-mcp

Integrations in flight

How agents call you

Try it against the live reference server with one command — no install:

curl -X POST https://onyx-actions.onrender.com/v1/onyx_solana_jupiter_quote \
  -H "content-type: application/json" \
  -d '{"input_mint":"So11111111111111111111111111111111111111112","output_mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"1000000000"}' -i
# → HTTP 402 Payment Required
# → payment-required: <base64-encoded JSON with payTo, asset, amount, inputSchema>

Then sign an EIP-3009 USDC authorization and retry with X-PAYMENT: <signed>:

# Full client demo — shows the 402 → sign → 200 loop in 50 lines:
python examples/agent_pay.py onyx_solana_jupiter_quote
# Set ONYX_DEMO_KEY=0x... to actually pay + get the result

Any x402-aware client SDK (Coinbase CDP, Cloudflare Agent SDK, Privy, mcp-use) handles the loop in ~5 lines. Agents don't need to know your URL — the Coinbase Bazaar crawler picks up your /.well-known/x402.json from on-chain settled payments.

Configure

The framework defaults are sane. Customize via constructor or env:

FieldDefaultNote
namerequiredshows up in MCP, manifest, landing page
receive_addressrequiredwhere USDC settles
networkbase-sepoliaor base for mainnet
facilitator_urlx402.org publicswap for Coinbase CDP / xpay / your own
public_urlNonesets the canonical URL in manifests
descriptionemptyshort one-liner
homepageNoneoptional landing page URL

Self-hosting checklist

  1. Generate or pick a Base wallet (just an address — private key never leaves your machine; this is a receive-only flow)
  2. Funded wallet not required to receive — only senders need USDC
  3. Pick a host: Render free tier works; Fly.io machines for always-on; Cloudflare Tunnel + Oracle ARM for zero-cost-zero-cold-start
  4. pip install onyx-paid-mcp, write your app.py, deploy
  5. Submit https://your-server/.well-known/x402.json to Coinbase Bazaar — first settled payment auto-indexes you everywhere

Status

v0.1.0 — released April 2026. Battle-tested on onyx-actions.onrender.com (live since Apr 24).

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados