MCP Overview

Quick summary

For AI-assisted protection of local source code, choose yp-mcp. For seller, donation, or license operations against a hosted backend, choose the remote gateway.

Start with the local setup or remote setup; do not expose write actions without real user approval.

The repo ships three MCP adapters, all speaking protocol version 2024-11-05 and all thin — none of them re-implements business logic:

Server	Artifact	Transport	Adapts	Tools
yp-mcp (local protect)	tools/devpay-mcp/ (@yetdapay/mcp)	line-delimited stdio JSON-RPC	the yp CLI — results are yp --json verbatim + receipt	6 yetdapay_* protect tools
yetdapay-mcp-gateway (remote)	mcp/gateway/ (Cloudflare Worker)	Streamable HTTP — one JSON-RPC per POST body, plain application/json (no SSE, no batching)	the YetdaPay REST API upstream	20 yetdapay_* tools (10 configure/validate + 10 read)
yetdapay-mcp (local commerce, Rust)	mcp/ crate	line-delimited stdio JSON-RPC	the Axum REST API (be/)	the original 10 commerce tools the gateway ported

All three share conventions: tool results are {content:[{type:"text",text:<json>}],isError} and every tools/call payload embeds a receipt {"receipt":{"tool","request_id","action":"read|write","at","ok"}}.

Which one do I use?

• Protect a module / run the pipeline from an agent → yp-mcp (local; wraps the CLI; approval-gated apply).
• Inspect stores, donations, feedback, licenses, usage, security events from a remote/hosted agent → the gateway.
• Same commerce tools against a local Axum backend with env-var credentials → the Rust stdio server (mcp/).

Error mapping

Condition	yp-mcp	gateway
JSON parse failure	-32700	-32700
Invalid request	-32600	-32600
Unknown method	-32601	-32601
Unknown tool name	-32601	-32602 (a ParamsError)
Argument validation	-32602	-32602
Tool execution failure	tool result isError:true + {error:{code,message}}	same
notifications/*	silent (no output)	202 empty body

Known divergence

yp-mcp maps an unknown tool name to -32601 ("tool not found"); the Rust adapter and the gateway map it to -32602 (invalid params). Noted in tools/devpay-mcp/server.mjs header comments and confirmed in mcp/gateway/worker.js (unknown tool → ParamsError).

Tool naming

Every tool across the MCP surface uses the yetdapay_* namespace — per the naming policy, new MCP additions keep this prefix even though they wrap @yetdapay/* packages.

Safety posture (short version)

• yp-mcp: spawns via execFile argv arrays (never a shell), realpath-contains all path args inside the workspace, scrubs the child env to an allowlist, and refuses apply without approved:true before any spawn. Analyze/plan/verify execute workspace code — trusted workspaces only. Details: Local Setup.
• Gateway: the client's Authorization: Bearer header is the seller credential — forwarded verbatim to seller-scope endpoints, never logged or stored; seller tools fail closed UNAUTHORIZED without it; /public/** upstream calls never carry credentials. Details: Authentication.