@easylabs/mcp-server

Easy Labs MCP Server

Easy Labs MCP Server is a Model Context Protocol (MCP) server that gives AI agents read-only access to payment processing data through the Easy API. This is the first MCP server focused on Easy Labs payment operations and is Phase 1 of the integration roadmap.

Features

• Read-only tools for transfers, disputes, settlements, customers, and balance transfers
• Merchant-focused resources for profile and summary context
• Stdio transport for local MCP clients (default)
• HTTP transport with SSE compatibility for remote/daemonized usage (--http)
• Strict TypeScript with Zod input validation
• Human-readable responses with formatted currency, dates, and statuses

Installation

npm install @easylabs/mcp-server

For local development in this repository:

npm install
npm run dev

Configuration

Set environment variables before running:

• EASY_API_KEY (required): Easy API key
• EASY_ENVIRONMENT (optional): Set to production to target the production API. Omit (or set to anything else) to use the sandbox. Default: sandbox.
• EASY_API_URL (optional): Explicit base URL override. Only hosts ending in .itseasy.co or localhost are accepted; any other value causes an immediate startup error so your key is never sent to an unknown host.
  • Sandbox default: https://sandbox-api.itseasy.co/v1/api
  • Production: https://api.itseasy.co/v1/api
• EASY_MCP_PORT (optional, HTTP mode only): HTTP server port
  • Default: 3100

Example (sandbox — default, no extra config needed):

export EASY_API_KEY="your_easy_api_key"

Example (production opt-in):

export EASY_API_KEY="your_easy_api_key"
export EASY_ENVIRONMENT="production"

Running the Server

Stdio (Default)

npm run dev

HTTP/SSE-Compatible Mode

npm run dev -- --http

Custom port:

npm run dev -- --http --port=3200

HTTP endpoint:

• http://127.0.0.1:<port>/mcp

Claude Desktop Configuration

Add this to claude_desktop_config.json:

Sandbox (default — safe starting point):

{
  "mcpServers": {
    "easy-labs": {
      "command": "npx",
      "args": ["-y", "@easylabs/mcp-server"],
      "env": {
        "EASY_API_KEY": "your_easy_api_key"
      }
    }
  }
}

Production opt-in:

{
  "mcpServers": {
    "easy-labs": {
      "command": "npx",
      "args": ["-y", "@easylabs/mcp-server"],
      "env": {
        "EASY_API_KEY": "your_easy_api_key",
        "EASY_ENVIRONMENT": "production"
      }
    }
  }
}

Other MCP Clients

Stdio Clients

Run as a child process:

EASY_API_KEY=your_easy_api_key npx @easylabs/mcp-server

HTTP Clients

Start server in HTTP mode and point client to:

• http://127.0.0.1:3100/mcp

Available Tools

• list_transfers - List recent transfers with optional limit, offset, status
• get_transfer - Get one transfer by transfer_id
• list_disputes - List disputes with optional limit, offset, state
• get_dispute - Get one dispute by dispute_id
• list_settlements - List settlements with pagination (limit, offset)
• get_settlement - Get one settlement by settlement_id
• list_customers - List customers with pagination (limit, offset)
• get_customer - Get one customer by customer_id
• list_balance_transfers - List balance transfers with pagination (limit, offset)
• get_balance_transfer - Get one balance transfer by balance_transfer_id

Available Resources

• merchant://profile - Current merchant profile info
• merchant://summary - Quick overview (recent volume, dispute rate, active settlements)
• docs://api-reference - Static API reference
• docs://changelog - Static changelog

Examples

Example: List Recent Transfers

Tool call:

{
  "name": "list_transfers",
  "arguments": {
    "limit": 5,
    "status": "completed"
  }
}

Example response format:

Recent Transfers (count: 2)

Transfer trf_123
Amount: $42.00
Status: ✅ completed
Customer: cus_abc
Created: Feb 27, 2026, 06:00:00 AM
Description: Subscription payment

Example: Get a Dispute

Tool call:

{
  "name": "get_dispute",
  "arguments": {
    "dispute_id": "dsp_123"
  }
}

Example: Read Merchant Summary Resource

Resource URI:

merchant://summary

Development

Build:

npm run build

Type-check:

npx tsc --noEmit

Roadmap

• Phase 1: Read-only tools and resources (this release)
• Phase 2: Write operations and workflow tooling

License

MIT