Fin-MCP Payment Server

Fin-MCP

Fin-MCP is a self-hosted, modular MCP that allows AI agents or enterprise systems to interact with multiple payment providers (e.g., Stripe, Paystack) via a single unified API. It abstracts the provider logic so agents can call payment operations seamlessly.

Features

MCP for Payments: AI agents can perform payment actions without knowing provider details.
Dynamic MCP tools: Initialize payment, verify payment, refund, create customers, and invoices.
Optional authentication: Protect MCP access with API keys.
Metadata endpoint: Agents can discover available tools and supported providers.
Self-hosted MCP: Full control over deployments and provider credentials.
Extensible: Add new tools or providers with minimal changes.
Protocol-driven tool execution: Agents can call any tool via /mcp/call.
Provider abstraction: MCP selects or routes to the appropriate payment provider automatically (e.g., based on provider like stripe, based on currency (soon)).

Installation

git clone https://github.com/Veri5ied/fin-mcp.git
cd fin-mcp

Install dependencies

bun install

Configuration

Create a .env file in the root:

# Enable or disable API key authentication
ENABLE_AUTH=false

# API key for auth (only used if ENABLE_AUTH=true)
FIN_MCP_KEY=supersecret-fin-key

# Stripe secret key (required for Stripe provider)
STRIPE_SECRET=sk_test_1234567890

ENABLE_AUTH: Set to true for secure access; false for testing or private networks.
FIN_MCP_KEY: Your self-generated secret key.
STRIPE_SECRET: Stripe API secret for payment operations.

Running the MCP

bun run dev

Open http://localhost:3000 in your browser.

API Endpoints

1. Get Metadata

GET /mcp/metadata

Agents discover available payment tools and providers

{
  "tools": [
    {
      "name": "initialize_payment",
      "description": "Start a payment",
      "providers": ["stripe", "paystack"]
    }
  ]
}

2. Call a Tool

POST /mcp/call

Agents execute payment operations through the MCP protocol.

Headers (if auth enabled):

Authorization: Bearer <FIN_MCP_KEY>
Content-Type: application/json

Body Example (Stripe Initialize Payment):

{
  "tool": "initialize_payment",
  "input": {
    "provider": "stripe",
    "amount": 5000,
    "currency": "USD",
    "email": "customer@example.com"
  },
  "idempotency_key": "unique-key-123"
}

Response:

{
  "status": "ok",
  "result": {
    "id": "cs_test_1234",
    "object": "checkout.session"
  }
}

Adding New Providers

Create a new adapter in src/providers/.
Implement the required interfaces (PaymentProvider, or extend specific tool interfaces).
Add the adapter to the provider registry (src/providers/registry.ts).
Update metadata.ts to include the new provider for relevant tools.

The MCP will automatically route calls based on the provider field in the request payload.

Development Notes

Idempotency: Use idempotency_key in /mcp/call to prevent duplicate operations.
Audit Logging: MCP logs every call via logAudit() for traceability.
Extensibility: You can define new tools without modifying the core callHandler — just add the tool interface and adapter implementation.
Optional Authentication: Set ENABLE_AUTH=false for testing or private self-hosted environments.

License

MIT License — free to use and modify for your self-hosted deployments.

💡 Optional Add-ons

Integrate AI agents to call /mcp/call dynamically.
Add support for webhooks from payment providers.
Add fully typed output interfaces for each provider to eliminate any responses.