@solvapay/mcp

Creates a Model Context Protocol server instance pre-configured with SolvaPay-specific tool registry and OAuth bridge bindings. Uses the @modelcontextprotocol/sdk base server factory pattern, wrapping it with SolvaPay's payment domain context (merchant accounts, transaction routing, webhook handlers). The createSolvaPayMcpServer function initializes the server with built-in tool discovery and registers payment-specific resources without requiring manual schema definition.

Provides two parallel OAuth credential exchange implementations — one for fetch-based runtimes (Cloudflare Workers, Deno, edge functions) and one for Express.js servers — that normalize OAuth flows to a common interface. Each variant handles provider-specific token exchange, refresh token rotation, and credential storage without requiring developers to write OAuth boilerplate. The adapter abstracts away HTTP client differences (fetch vs axios) and server framework patterns (middleware vs handler functions).

Registers payment-specific tool handlers into the MCP tool registry using a declarative schema system (registerPayableTool function). Each tool definition includes JSON schema for inputs, output type hints, and a handler function that receives normalized payment context (merchant ID, transaction state, audit trail). The registration system validates schemas at initialization time and binds handlers to MCP's function-calling protocol, enabling LLMs to invoke payment operations with type safety and automatic input validation.

Automatically discovers and exposes available payment tools and resources through the MCP resource protocol, allowing LLM clients to query what operations are available without hardcoding tool lists. The discovery mechanism scans the registered tool registry at runtime and generates MCP-compatible resource descriptions (name, description, input schema, output type). This enables dynamic tool discovery in Claude Desktop and other MCP clients that support resource enumeration.

Routes incoming webhook events from SolvaPay (transaction completed, refund processed, dispute filed) to registered event handlers via an event emitter pattern. The webhook adapter validates webhook signatures using HMAC-SHA256, deserializes payment event payloads, and dispatches them to handler functions that can trigger side effects (database updates, LLM notifications, compliance alerts). Supports both synchronous handlers (return immediately) and asynchronous handlers (queue for background processing).

Automatically enriches payment tool handler context with transaction metadata (merchant ID, user ID, timestamp, LLM model/session ID) and generates immutable audit trail entries for every payment operation. The enrichment layer intercepts tool calls, extracts context from the MCP request envelope, and injects it into handler functions. Audit entries include the original LLM prompt, tool inputs, outputs, and any errors, enabling post-hoc compliance review and debugging of AI-driven payment decisions.

Abstracts payment operations (charge, refund, reconcile) across multiple payment providers (SolvaPay, Stripe, PayPal) through a unified tool interface. Each provider has a backend implementation that translates normalized tool calls to provider-specific APIs, handles provider-specific error codes, and normalizes responses back to a common schema. The abstraction layer allows LLM agents to invoke payment tools without knowing which provider is configured, enabling provider switching without changing agent code.