Yugo MCP Server

Yugo MCP Server

An MCP (Model Context Protocol) server for the Yugo Payments API. Auto-generates tools from the OpenAPI spec — new API endpoints are supported with zero code changes.

Features

• OpenAPI-driven — Tools are auto-generated from the Yugo OpenAPI spec
• Future-proof — New endpoints auto-register when the spec is updated
• Dual transport — stdio (local) and SSE (remote) support
• MCP Resources — Exposes the OpenAPI spec and payment rails reference data
• Idempotency — Auto-generates idempotency keys for POST requests
• Error handling — Parses RFC 9457 problem details into readable messages

Quick Start

1. Install dependencies

npm install

2. Configure environment

cp .env.example .env
# Edit .env and set your YUGO_API_KEY

3. Build & run

npm run build
npm start

Or for development:

npm run dev

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | YUGO_API_KEY | Yes | — | Your Yugo API key (contact support@yugo.finance) | | YUGO_BASE_URL | No | https://sandbox-api.yugo.finance/api/v2 | API base URL. Set to https://api.yugo.finance/api/v2 for production | | TRANSPORT | No | stdio | Transport type: stdio or sse | | PORT | No | 3000 | HTTP port (only used with SSE transport) |

Available Tools

Auto-generated from the OpenAPI spec. Currently includes:

| Tool | Description | |------|-------------| | create_payin | Create a new payin — accept funds from a payer | | get_payin_by_id | Get payin details by ID | | get_payins | List payins (paginated, filterable by reference) | | create_payout | Create a new payout — send funds to a recipient | | get_payout_by_id | Get payout details by ID | | get_payouts | List payouts (paginated, filterable by reference) | | get_banks | List available banks for open banking | | get_accounts | List merchant accounts and balances |

MCP Resources

| URI | Description | |-----|-------------| | yugo://spec | Full OpenAPI 3.1 specification | | yugo://rails | Supported payment methods, settlement methods, and currencies |

Usage with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "yugo": {
      "command": "node",
      "args": ["/path/to/yugo-mcp-server/dist/index.js"],
      "env": {
        "YUGO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usage with Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "yugo": {
      "command": "node",
      "args": ["/path/to/yugo-mcp-server/dist/index.js"],
      "env": {
        "YUGO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Usage with SSE (Remote)

TRANSPORT=sse PORT=3000 YUGO_API_KEY=your_key node dist/index.js

Connect your MCP client to http://localhost:3000/sse.

Updating the OpenAPI Spec

To pick up new API endpoints:

curl -sL https://docs.yugo.finance/openapi/payments.yaml -o openapi/payments.yaml
npm run build

Restart the server and new tools will be available automatically.

Architecture

This server is the MCP Server interface layer in the Yugo System Architecture. It runs as a separate process that calls the Yugo REST API.

AI Agent → MCP Server → Yugo REST API → Payment Core → Settlement Rails

License

MIT