Yugo 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 [email protected])
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