mcp server instantiation with solvapay payment context
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.
Unique: Pre-wires SolvaPay payment domain context directly into MCP server factory, eliminating manual tool schema definition and OAuth bridge setup — developers get a payment-ready server in one function call rather than assembling MCP primitives
vs alternatives: Faster than building custom MCP servers from @modelcontextprotocol/sdk alone because SolvaPay-specific tool schemas, error handling, and OAuth flows are pre-integrated rather than hand-coded
runtime-agnostic oauth bridge adapter (fetch/express variants)
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).
Unique: Dual-implementation pattern (fetch + Express) with unified interface allows same OAuth logic to run on edge functions and traditional servers without adapter layers — achieved via runtime detection and conditional imports rather than abstract base classes
vs alternatives: More portable than passport.js (Express-only) or custom OAuth handlers because it natively supports both serverless and traditional runtimes with identical credential semantics
payable tool registration with schema-based function binding
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.
Unique: Combines MCP tool registration with payment-domain context injection — handlers receive pre-bound merchant ID and transaction state rather than requiring developers to extract context from raw LLM inputs, reducing error surface in financial operations
vs alternatives: Safer than raw function calling because schema validation + audit logging are mandatory, not optional — prevents malformed payment requests and creates compliance-ready transaction records automatically
mcp resource discovery and tool enumeration
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.
Unique: Integrates with MCP's native resource protocol rather than implementing custom discovery endpoints — allows MCP clients to use standard resource queries to enumerate payment tools, maintaining protocol compatibility
vs alternatives: More discoverable than custom API documentation because MCP clients can query available tools programmatically and render them in UI, vs requiring developers to read docs or maintain tool lists
webhook event routing and async payment notifications
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).
Unique: Combines webhook signature validation with MCP tool invocation — handlers can directly call registered payment tools to respond to events, enabling closed-loop payment automation (e.g., webhook triggers refund tool, which updates LLM agent state)
vs alternatives: More secure than custom webhook handlers because HMAC validation is mandatory and built-in, vs requiring developers to implement signature verification separately
transaction context enrichment and audit trail generation
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.
Unique: Intercepts MCP tool calls at the framework level to inject transaction context and generate audit entries automatically — developers don't need to manually log or track context, reducing compliance burden and error surface
vs alternatives: More comprehensive than manual logging because it captures the full decision chain (prompt → tool call → result) automatically, vs requiring developers to instrument each payment operation separately
multi-provider payment tool abstraction
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.
Unique: Implements provider abstraction at the tool handler level rather than as a separate adapter layer — each registered tool has a provider-specific backend, allowing LLM clients to call tools without knowing provider details
vs alternatives: More flexible than provider-specific SDKs because agents can work with any provider without code changes, vs Stripe SDK or PayPal SDK which lock you into a single provider