CASE STUDY · /paybito-mcp

PayBito Integration MCP — AI Agent Knowledge Server

A Model Context Protocol server that injects PayBito's full API surface into any MCP-capable AI assistant — letting developers write correct integration code in plain language. Read-only by design; ships as dual-language packages on PyPI + npm from one source of truth.

ROLE

Sole Author · Architect · Spec Engineer

TIMELINE

2025

TEAM

1 (solo, AI-augmented)

STATUS

Published · PyPI + npm · Read-only

LIVE

↗ Website

Overview

A Model Context Protocol (MCP) knowledge server that PayBito developers plug into Claude Code, Cursor, Codex, or Gemini — and immediately get correct, scoped, auth-aware PayBito integration code from natural-language requests.

Read-only by design: the server distributes documentation and request shapes only. It never executes live calls, never reads balances, never moves funds. The threat model is documentation accuracy, not runtime trust.

Shipped as two published packages from one source of truth — paybito-mcp on PyPI (FastMCP) and on npm (@modelcontextprotocol/sdk) — backed by a shared generated model and a regression test suite.

The problem

PayBito publishes OpenAPI specs across many hosts and product surfaces (exchange, payments, gateway, platform). Specs have practical quirks — hostnames baked into path keys, missing securitySchemes, empty servers fields, overlapping operations across hosts — and developers integrating PayBito routinely call the wrong endpoint, pass the wrong auth scheme, or miss nested request bodies. Documentation tells you it works; the AI assistant tells you exactly how, in your code.

What I built

Spec-normalization pipeline: distills ~1,060 unique operations across multiple OpenAPI hosts into one clean model — repairs spec quirks, deduplicates, resolves auth realm per operation
Intent-based product routing: server asks one question — "what are you building?" — and scopes results to the right module (exchange / payments / gateway / platform), so a merchant-payments request never resolves to the trading API
White-label base-URL handling: emits a developer-supplied BASE_URL rather than hardcoding hosts — works for any PayBito tenant deployment
Multi-scheme per-operation auth + payments test/live sandbox awareness — exact auth shape returned with every operation
Read-only contract: only MCP Resources, Prompts, and Tools that return documentation; no execution surface
Dual-language publish: Python (FastMCP) + TypeScript (@modelcontextprotocol/sdk) from a shared generated model — same operations, same auth resolution, same intent routing in both
Regression test suite that locks the normalization output — spec drift caught at CI before publish

Tech stack

Model Context ProtocolFastMCP (Python)@modelcontextprotocol/sdk (TypeScript)OpenAPI 3.x normalizationPyPInpmJSON SchemaPydanticZod

Outcome

Live on PyPI (pypi.org/project/paybito-mcp) and npm (npmjs.com/package/paybito-mcp). PayBito's full API surface — ~1,060 normalized operations, intent-routed by product, auth-aware, base-URL-portable — is now first-class context inside any MCP-capable AI assistant. Developers can ask in English; the model returns correct integration code with the right host, auth, and request body shape.

Want this in your stack? Let's talk.

Email Athar Back to all projects