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 GitHubFramework 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-mcp1 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
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
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/.
| Tool | Price |
|---|---|
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
- Stagehand (Browserbase) — pay-per-call captcha hook over x402. Spec:
BROWSERBASE_INTEGRATION.md. Discussion: #1.
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:
| Field | Default | Note |
|---|---|---|
name | required | shows up in MCP, manifest, landing page |
receive_address | required | where USDC settles |
network | base-sepolia | or base for mainnet |
facilitator_url | x402.org public | swap for Coinbase CDP / xpay / your own |
public_url | None | sets the canonical URL in manifests |
description | empty | short one-liner |
homepage | None | optional landing page URL |
Self-hosting checklist
- Generate or pick a Base wallet (just an address — private key never leaves your machine; this is a receive-only flow)
- Funded wallet not required to receive — only senders need USDC
- Pick a host: Render free tier works; Fly.io machines for always-on; Cloudflare Tunnel + Oracle ARM for zero-cost-zero-cold-start
pip install onyx-paid-mcp, write yourapp.py, deploy- Submit
https://your-server/.well-known/x402.jsonto 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.