@easylabs/mcp-server

Easy Labs MCP Server

Give AI agents access to your Easy payment data through the Model Context Protocol. Ask your agent "how's revenue this month?" or "find [e-mail] and show her recent payments" and get real answers from your account — read-only, sandbox-first.

Easy (itseasy.co, by Easy Labs, Inc.) is a self-custodial payment platform: businesses accept cards, ACH, wallets, and stablecoins with flat-rate pricing, next-day payouts, and cashback on idle balances. Docs: docs.itseasy.co · Machine-readable site index: itseasy.co/llms.txt

Try it in 60 seconds — no account needed

Demo mode serves a deterministic, obviously-fake dataset ("Demo Coffee Co.", demo_* ids, @example.com emails) with zero network calls, so you can explore every tool before you have an API key.

Claude Desktop / any MCP client — add to your MCP config:

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

Claude Code:

claude mcp add easy-labs-demo -e EASY_ENVIRONMENT=demo -- npx -y @easylabs/mcp-server

Then ask: "Give me a revenue summary for the last 30 days" · "Find the customer [e-mail]" · "Any open disputes?"

Connect your real account

Get an API key from the Easy dashboard (signup). The server targets the sandbox by default — production is an explicit opt-in:

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

To target production instead of the sandbox, add "EASY_ENVIRONMENT": "production" to env — deliberately explicit, never the default.

Tools

Workflow tools answer whole questions in one call — prefer them when they fit:

Tool	What it answers
revenue_summary	"How's revenue?" — gross volume, counts by status, average ticket, success rate, and change vs the previous period (7d/30d/90d/6m/12m/mtd)
find_customer	"Who is jane@…?" — email/name search plus the best match's profile and recent payments

Read-only building blocks:

Tool	Purpose
list_transfers / get_transfer	Payments, filterable by status
list_disputes / get_dispute	Chargebacks and their lifecycle state
list_settlements / get_settlement	Payout batches
list_customers / get_customer	Customer records
list_balance_transfers / get_balance_transfer	Balance movements

Resources: merchant://profile, merchant://summary (account context for the agent), docs://api-reference, docs://changelog.

All tools are read-only (readOnlyHint: true) — nothing here moves money.

Notes for AI agents

• No credentials? Use demo mode (EASY_ENVIRONMENT=demo, or the literal credential demo against a hosted endpoint). Demo data self-identifies: demo_* ids, @example.com emails.
• Start with revenue_summary / find_customer; fall back to list_*/get_* for specifics. Read merchant://summary for account context.
• Amounts are integer cents, USD unless stated. Errors are human-readable strings including the HTTP status; 404 means the id doesn't exist.
• To learn about the Easy product itself, fetch itseasy.co/llms.txt — every page there is available as markdown.

HTTP mode (Streamable HTTP, multi-tenant)

npx -y @easylabs/mcp-server --http          # port 3100, or EASY_MCP_PORT / PORT / --port=

• POST/GET/DELETE /mcp — MCP endpoint · GET /health — liveness, no auth
• Auth is per-request: x-easy-api-key: sk_... or Authorization: Bearer sk_... — live keys route to the production API, test keys to the sandbox. EASY_API_KEY is only a fallback for keyless requests. Sessions are bound to the credential that opened them.
• Keyless requests get a demo session — zero-config tool discovery with self-identifying sample data. The literal credential demo does the same explicitly. Set EASY_MCP_KEYLESS=reject for strict 401s on private deployments. Real data always requires a valid key; an invalid key fails at the API, never downgrading to demo.
• Per-key rate limiting: EASY_MCP_RATE_LIMIT_PER_MINUTE (default 120); 429s carry Retry-After + RateLimit-*.
• Idle sessions evicted after 30 minutes.

Configuration reference

Variable	Default	Purpose
EASY_API_KEY	—	API key (required for stdio real mode; per-request fallback in HTTP mode)
EASY_ENVIRONMENT	sandbox	production targets the live API; demo serves sample data with no key
EASY_API_URL	per environment	Advanced override — only *.itseasy.co / localhost hosts are accepted, so your key can never be sent elsewhere
EASY_MCP_PORT / PORT	3100	HTTP mode port
EASY_MCP_RATE_LIMIT_PER_MINUTE	120	HTTP per-key rate limit
EASY_MCP_KEYLESS	serve demo	Set to reject to 401 keyless HTTP requests instead of serving demo data

Safety model

• Read-only tool surface — no writes, no money movement.
• Sandbox by default; production requires EASY_ENVIRONMENT=production.
• Host allowlist: the client refuses to send your API key anywhere but *.itseasy.co/localhost.
• Keys are never logged; multi-tenant session state stores only a hash.

Development

pnpm install
pnpm dev                 # stdio (set EASY_ENVIRONMENT=demo or EASY_API_KEY)
pnpm dev -- --http       # Streamable HTTP on :3100
pnpm test                # vitest — includes end-to-end transport tests
pnpm type:check && pnpm build

Links

• Developer portal · Docs · MCP docs · Status
• Support: [e-mail]