paybito-mcp 0.1.4

PayBito infrastructure knowledge helper for AI agents — injects PayBito API expertise (Resources + Prompts, no live actions) into any MCP-capable AI platform.

PayBito MCP — AI Integration Knowledge Helper

A knowledge helper that injects PayBito infrastructure expertise into any AI coding agent, so a developer can implement PayBito integrations (websites, exchanges, payment flows, trading apps) in natural language.

It is not an action executor. It never calls PayBito's live API, never moves funds, never reads balances. It serves documentation and code guidance so the AI writes the correct integration code for you — the same way the frontend-design skill makes an AI produce great UIs without "running" anything.

Built from all 6 of PayBito's published OpenAPI specs (1,344 endpoints → 1,058 unique operations across 28 domains and 6 hosts), normalized into one clean model.

What it exposes

Surface	Contents	For
Resources	paybito://overview, paybito://auth, paybito://domains, paybito://domain/{slug}, paybito://operation/{id}, paybito://playbook/{name}	Clients that read MCP resources (Claude)
Tools (read-only)	paybito_overview, paybito_search, paybito_get_operation, paybito_get_domain, paybito_get_auth, paybito_list_playbooks, paybito_get_playbook	Clients that only invoke tools (ChatGPT, Cursor, Gemini, …). These return documentation only.
Prompts	integrate_paybito, add_payment_button, spot_trading_code	Guided workflows

Install

pip install -e .          # or: pipx install .   /   uvx --from . paybito-mcp
paybito-build             # generate build/model.json + build/corpus from specs/

paybito-mcp then runs the server over stdio.

Inject it into your AI (one-time setup per tool)

There are two delivery modes. Use the MCP server for agentic/coding tools, and the portable bundle for web chat UIs.

Mode A — MCP server (agentic & coding tools)

The command is paybito-mcp (after pip install), or npx -y paybito-mcp once published (see typescript/).

Claude Code

claude mcp add paybito -- paybito-mcp          # then: /mcp to verify it's connected

Claude Desktop — edit claude_desktop_config.json (Windows: %APPDATA%\Claude\, macOS: ~/Library/Application Support/Claude/):

{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }

Cursor — .cursor/mcp.json in your project (or global ~/.cursor/mcp.json):

{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }

VS Code (Copilot agent mode) — .vscode/mcp.json:

{ "servers": { "paybito": { "type": "stdio", "command": "paybito-mcp" } } }

OpenAI Codex CLI — ~/.codex/config.toml:

[mcp_servers.paybito]
command = "paybito-mcp"

Gemini CLI — ~/.gemini/settings.json:

{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }

ChatGPT (Developer mode / connectors) — host the server over HTTP and add it as a custom connector. (Local stdio is for desktop tools; for ChatGPT web, prefer Mode B or a hosted HTTP deployment.)

If paybito-mcp isn't on your PATH, use the absolute path, or { "command": "python", "args": ["-m", "paybito_mcp.server"] }.

Mode B — Portable knowledge bundle (web chat UIs, no install)

Run paybito-build, then upload the generated build/corpus/ folder as knowledge files:

• ChatGPT — Custom GPT → Configure → Knowledge (upload the files), or a Project's files.
• Claude (web/Projects) — create a Project → add the files to Project knowledge.
• Gemini (Gems) — create a Gem → add the files as knowledge.

Start the system/instruction with: "Use the PayBito knowledge files to write integration code; read overview.md and auth.md first."

Use cases — what to ask, and what the AI does

Once injected, the developer works in plain language. Examples:

You ask…	The AI does (via this knowledge)
"Add a PayBito crypto payment button to my WooCommerce checkout."	Reads the woocommerce + payment-button playbooks, pulls GetMerchant_settings / payNowCheckout / get_invoice_status_paid_amount fields, and writes a PHP gateway plugin with correct X-MBX-APIKEY auth and settlement polling.
"Build a Node endpoint to place a spot limit buy and check the order."	Reads spot-trading, gets tradeCreateOffer, getUserBalance, assetpairPrecision, and writes server-side code with precision + error handling and a ⚠️ confirmation step.
"Generate a Python client for PayBito withdrawals."	Finds createWithdrawalOrder / validateAddress / getFees, flags them as state-changing, and writes a client that validates the address and confirms before sending.
"How do I launch my own branded exchange on PayBito?"	Reads build-your-platform, surveys the Broker/Exchange/Access-Control domains, and outlines the onboarding + OAuth + configuration calls with the correct institutional-bo host.
"What does the response of getUserBalance look like?"	Calls paybito_get_operation and returns the documented fields + a ready request example.

The AI writes the code; you run it. The server never executes a PayBito call itself.

Quick prompts (MCP prompts)

In MCP-aware clients you can also invoke the bundled prompts directly: integrate_paybito, add_payment_button, use_playbook, spot_trading_code.

Rebuild when PayBito updates their specs

The specs in specs/ were downloaded from the Redoc spec-url endpoints under https://service.hashcashconsultants.com/Api/…. Re-download them and run paybito-build.

Architecture

specs/*.yaml ──► normalize.py ──► build/model.json ──► corpus.py ──► resources/tools/prompts
  (6 OpenAPI)     (Phase 0:          (1,058 unique     (Phase 1:        (server.py)
                   repair quirks,     operations,       layered
                   merge, dedup)      provenance)       markdown)

Spec quirks the normalizer repairs: empty servers.url; hostnames + query strings baked into path keys; missing securitySchemes (auth is prose-only); 6 mixed hosts incl. WebSocket pseudo-endpoints; heavy overlap across the 6 files.

Auth model (for generated code)

⚠️ PayBito uses three different auth schemes by product — the server resolves the right one per operation (see each operation's Authentication section, or paybito://auth):

• Exchange / Trading (accounts.paybito.com) — one header X-MBX-APIKEY: base64(API_KEY:SECRET).
• Payments Platform — two verbatim headers X-MBX-APIKEY: <key> + X-MBX-SECRETKEY: <secret> (not base64), plus Origin + IP whitelisting on private endpoints.
• Cart / Checkout V2 — X-MBX-PUBLIC-KEY + CLIENT-SECRET-KEY (call createClientSecretKey first to get the per-domain secretHash; see the cart-v2-pk-domain playbook).
• Build-your-exchange / launch — Authorization: Bearer <JWT> from the login endpoint.

Permissions: READ / DEPOSIT / WITHDRAW / TRADE. Rate limit 5 req/s per IP.