Easy Labs MCP Server
Payments data, revenue workflows, and merchant-application guidance for AI agents, by Easy Labs.
Open source Repository Open in the app JSON README (API)
About
Payments data, revenue workflows, and merchant-application guidance for AI agents, by Easy Labs.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- co.itseasy
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.5.0
- Added
- 2026-08-29 03:00:51
- Updated
- 2026-09-13 03:08:55
- Origin id
co.itseasy/easy-mcp
README
# Easy Labs MCP Server
Give AI agents access to your [Easy](https://www.itseasy.co) payment data through the [Model Context Protocol](https://modelcontextprotocol.io). Ask your agent *"how's revenue this month?"* or *"find ava.chen@example.com 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](https://docs.itseasy.co) · Machine-readable site index: [itseasy.co/llms.txt](https://www.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:
```json
{
"mcpServers": {
"easy-labs-demo": {
"command": "npx",
"args": ["-y", "@easylabs/mcp-server"],
"env": { "EASY_ENVIRONMENT": "demo" }
}
}
}
```
**Claude Code:**
```bash
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 ava.chen@example.com"* · *"Any open disputes?"*
## Connect your real account
Get an API key from the [Easy dashboard](https://app.itseasy.co) ([signup](https://www.itseasy.co)). The server targets the **sandbox by default** — production is an explicit opt-in:
```json
{
"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](https://www.itseasy.co/llms.txt) — every page there is available as markdown.
## HTTP mode (Streamable HTTP, multi-tenant)
```bash
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
```bash
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](https://www.itseasy.co/developers) · [Docs](https://docs.itseasy.co) · [MCP docs](https://docs.itseasy.co/docs/sdks/mcp) · [Status](https://status.itseasy.co)
- Support: support@itseasy.co