MONEI MCP Server

Connect your MONEI payment account to AI assistants like Claude and ChatGPT using the Model Context Protocol.

Generate payment links, check transaction status, and browse your payment history — all through natural language conversation.

Features

• 🔗 Payment Links — Create and share payment links with customers via AI
• 🔍 Transaction Lookup — Get payment details and status by ID
• 📊 Payment History — Search and filter your transaction history
• 📋 Subscriptions — View subscription details and status
• 🏢 Account Info — Access your merchant account configuration
• 🔐 OAuth 2.0 — Secure merchant authentication with scoped permissions
• 🛡️ Guardrails — Restricted operations are hard-blocked, not just hidden

Security by Design

This server enforces strict guardrails on what operations AI assistants can perform. The following operations are explicitly blocked at the server level:

Blocked Operation	Reason
Refund payments	Financial risk — use MONEI Dashboard
Charge cards/Bizum	Requires PCI context and cardholder consent flows
Card payouts	Funds disbursement requires compliance controls
Bizum payouts	Outbound money movement requires compliance controls
Cancel subscriptions	Destructive action — use Dashboard
Modify account settings	Security-sensitive — use Dashboard

Even if a tool call is crafted manually, restricted endpoints will reject it with a clear explanation and redirect to the Dashboard.

Quick Start

Prerequisites

• Node.js 18+
• A MONEI account with API credentials

Installation

git clone https://github.com/MONEI/MONEI-MCP-Server.git
cd MONEI-MCP-Server
npm install

Configuration

cp .env.example .env

Edit .env with your MONEI credentials:

MONEI_CLIENT_ID=your_client_id
MONEI_CLIENT_SECRET=your_client_secret
MONEI_API_KEY=your_api_key  # For development/testing

Run

# Development (with hot reload)
npm run dev

# Production
npm run build
npm start

The server starts at http://localhost:3000 with:

• Streamable HTTP (recommended): /mcp — Connect AI assistants here
• Legacy SSE: /sse — Backward compatibility
• Health check: /health — Server status
• OAuth: /oauth/authorize — Merchant authorization flow

Connecting to Claude

Claude.ai (Connectors Directory)

Once listed in the Anthropic Connectors Directory, merchants can connect with one click from Customize → Connectors in Claude.ai.

For custom connector setup:

1. Go to Customize → Connectors → Add
2. Add your server URL: https://your-domain.com/mcp
3. Complete the OAuth authorization flow

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "monei": {
      "url": "https://your-domain.com/mcp"
    }
  }
}

Claude Code

claude mcp add monei --transport http https://your-domain.com/mcp

Available Tools

generate_payment_link

Create a shareable payment URL.

"Generate a €25 payment link for order #1234 — customer is [email protected]"

get_payment

Retrieve payment details by ID.

"What's the status of payment abc123?"

list_payments

Search and filter transaction history.

"Show me all successful payments from last week"

get_subscription

View subscription details.

"Get the details of subscription sub_xyz"

list_subscriptions

Browse subscriptions.

"List all active subscriptions"

get_account_info

View merchant account details.

"What payment methods do I have enabled?"

Architecture

src/
├── index.ts              # Entry point — Streamable HTTP + SSE + OAuth routes
├── server.ts             # MCP server setup + tool registration
├── auth/
│   ├── oauth.ts          # OAuth 2.0 + PKCE + scope validation
│   ├── pkce.ts           # RFC 7636 PKCE implementation
│   └── session.ts        # Single-use OAuth state manager (CSRF protection)
├── api/
│   └── monei-client.ts   # MONEI REST API client (allowed ops only)
├── tools/
│   ├── index.ts          # Tool registry + routing + restriction enforcement
│   ├── payments.ts       # Payment tools with safety annotations
│   ├── subscriptions.ts  # Subscription tools with safety annotations
│   └── account.ts        # Account info tool with safety annotations
├── middleware/
│   ├── security.ts       # CORS, HTTPS, session validation, input guard
│   ├── rate-limiter.ts   # Per-account sliding window rate limiter
│   └── audit-logger.ts   # Structured JSON audit logging
└── types/
    └── index.ts          # Shared types + restricted operations registry

tests/
├── auth/                 # PKCE, session, scope validation tests
├── middleware/            # Rate limiter, audit logger, security tests
└── tools/                # Restriction enforcement, routing, validation tests

Roadmap

• Streamable HTTP transport (Anthropic directory requirement)
• Tool safety annotations (readOnlyHint / destructiveHint)
• PKCE (RFC 7636) + CSRF state validation
• Security hardening (Helmet, CORS, rate limiting, audit logging)
• Comprehensive test suite
• Production OAuth 2.0 integration with MONEI auth service
• Persistent token storage (Redis/PostgreSQL)
• Anthropic Connectors Directory submission
• Webhook notifications for payment status changes
• Docker container + deploy-to-cloud templates
• NPM package publishing (npx @monei/mcp-server)
• Claude Desktop Extension (.mcpb bundle)

API Documentation

• MONEI API Reference
• MONEI Postman Collection
• MCP Specification

License

MIT © MONEI