{"_id":"@avenia-io/mcp-client","_rev":"3-7d537c1a0ecc9804a7a08efb96ffddb4","name":"@avenia-io/mcp-client","dist-tags":{"latest":"0.4.0"},"versions":{"0.2.0":{"name":"@avenia-io/mcp-client","version":"0.2.0","keywords":["avenia","mcp","model-context-protocol","payments","fintech","stablecoin","pix","claude","cursor"],"author":{"name":"Avenia"},"license":"MIT","_id":"@avenia-io/mcp-client@0.2.0","maintainers":[{"name":"avenia","email":"tech@avenia.io"}],"homepage":"https://api-reference.avenia.io","bugs":{"url":"https://github.com/Avenia-io/avenia-mcp/issues"},"bin":{"avenia-mcp":"dist/index.js","mcp-client":"dist/index.js"},"dist":{"shasum":"c0af4874631206f4cc8431ee48020acd0455c8d6","tarball":"https://registry.npmjs.org/@avenia-io/mcp-client/-/mcp-client-0.2.0.tgz","fileCount":6,"integrity":"sha512-ku0qRNjxcKtjk/+AMxbbIMw36RUpypfLAVWtOfTFoGw+S8VapZt9eV5WCQpUfAlXHb84h/zTy/zYw3K/32AVUg==","signatures":[{"sig":"MEYCIQDJi62Eg9Lz8yxGVwBQtLZqOMhttk9iV/1XHknq1pTdFgIhAKsRrC3Yw6CK25zOdnVj1zuV3Pdq2jReUpVQe0vPWVmJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":118964},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"447d8d0cdfeb97eebf5cb6a31e5c1350702b8afa","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsup src/index.ts --format esm --target node20 --clean --dts && node -e \"const f=require('fs'),p='dist/index.js';f.writeFileSync(p,'#!/usr/bin/env node\\n'+f.readFileSync(p,'utf8'));f.chmodSync(p,0o755)\"","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"avenia","email":"tech@avenia.io"},"overrides":{"hono":"^4.12.18","ip-address":"^10.2.0"},"repository":{"url":"git+https://github.com/Avenia-io/avenia-mcp.git","type":"git"},"_npmVersion":"11.13.0","description":"Official MCP server for the Avenia public API. Connect Claude Code, Cursor, Zed, and other MCP clients to the Avenia platform.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"zod":"^3.23.8","undici":"^6.21.0","@modelcontextprotocol/sdk":"^1.10.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.6.0","@types/node":"^22.7.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-client_0.2.0_1784077153665_0.2033828455881035","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@avenia-io/mcp-client","version":"0.2.2","keywords":["avenia","mcp","model-context-protocol","payments","fintech","stablecoin","pix","claude","cursor"],"author":{"name":"Avenia"},"license":"MIT","_id":"@avenia-io/mcp-client@0.2.2","maintainers":[{"name":"avenia","email":"tech@avenia.io"}],"homepage":"https://api-reference.avenia.io","bugs":{"url":"https://github.com/Avenia-io/avenia-mcp/issues"},"bin":{"avenia-mcp":"dist/index.js","mcp-client":"dist/index.js"},"dist":{"shasum":"0bf43d194bbee93619e882c626b446c414d51081","tarball":"https://registry.npmjs.org/@avenia-io/mcp-client/-/mcp-client-0.2.2.tgz","fileCount":6,"integrity":"sha512-UOCIPc67HWjjOVgkp8qHtwvmK01yMHCj3vzi75OumvOblCVpdDExclykBwgLmqgFCKPeaKBAoE6D/G/l5QrgQg==","signatures":[{"sig":"MEUCIQC6PWgIULDFDiGmiqxkGAuoHqOPdleJqOCE6rZyhHe9BQIgVeb43iSEmHLfhFEN3ZykDLKMaIwmvZ8PjjRm1cJVzZI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":125600},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"c86fcbe209228f5a671f966c85c960b32e911e8e","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsup src/index.ts --format esm --target node20 --clean --dts && node -e \"const f=require('fs'),p='dist/index.js';f.writeFileSync(p,'#!/usr/bin/env node\\n'+f.readFileSync(p,'utf8'));f.chmodSync(p,0o755)\"","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"avenia","email":"tech@avenia.io"},"overrides":{"hono":"^4.12.18","ip-address":"^10.2.0"},"repository":{"url":"git+https://github.com/Avenia-io/avenia-mcp.git","type":"git"},"_npmVersion":"11.13.0","description":"Official MCP server for the Avenia public API. Connect Claude Code, Cursor, Zed, and other MCP clients to the Avenia platform.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"zod":"^3.23.8","undici":"^6.21.0","@modelcontextprotocol/sdk":"^1.10.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.6.0","@types/node":"^22.7.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-client_0.2.2_1784164131268_0.24748875742399457","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@avenia-io/mcp-client","version":"0.4.0","description":"Official MCP server for the Avenia public API. Connect Claude Code, Cursor, Zed, and other MCP clients to the Avenia platform.","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"avenia-mcp":"dist/index.js","mcp-client":"dist/index.js"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"build":"tsup src/index.ts --format esm --target node20 --clean --dts && node -e \"const f=require('fs'),p='dist/index.js';f.writeFileSync(p,'#!/usr/bin/env node\\n'+f.readFileSync(p,'utf8'));f.chmodSync(p,0o755)\"","dev":"tsx src/index.ts","typecheck":"tsc --noEmit","test":"vitest run","prepublishOnly":"npm run build"},"keywords":["avenia","mcp","model-context-protocol","payments","fintech","stablecoin","pix","claude","cursor"],"author":{"name":"Avenia"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Avenia-io/avenia-mcp.git"},"homepage":"https://api-reference.avenia.io","engines":{"node":">=20.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.10.0","undici":"^6.21.0","zod":"^3.23.8"},"overrides":{"hono":"^4.12.18","ip-address":"^10.2.0"},"devDependencies":{"@types/node":"^22.7.0","tsup":"^8.3.0","tsx":"^4.19.0","typescript":"^5.6.0","vitest":"^2.1.0"},"gitHead":"3bb1936457132bf10bb22b1a413a49b4965ad7b7","_id":"@avenia-io/mcp-client@0.4.0","bugs":{"url":"https://github.com/Avenia-io/avenia-mcp/issues"},"_nodeVersion":"25.9.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-GpBS5iyRmxAqoVzcAxXSx5Zkj1pxIa1A/neDiFAoSx4Gff+Nnj7TfJ53QFm2sl0sPzvJOFB8sQ2brhhXBvFJyQ==","shasum":"a92d42d6c51a69ad54b8768837ba2c587509ae17","tarball":"https://registry.npmjs.org/@avenia-io/mcp-client/-/mcp-client-0.4.0.tgz","fileCount":6,"unpackedSize":140554,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHv3CvYR9Tq+teeY0XqYgx6ZeLoPhL4XclTZT0Ip9IYKAiAS2uS/pBnjBzRVV9sKsmpj/V6GQ170WQgORXLWNbqjdA=="}]},"_npmUser":{"name":"avenia","email":"tech@avenia.io"},"directories":{},"maintainers":[{"name":"avenia","email":"tech@avenia.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-client_0.4.0_1784248835422_0.7846264235392637"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-15T00:59:13.459Z","modified":"2026-07-17T00:40:35.745Z","0.2.0":"2026-07-15T00:59:13.808Z","0.2.2":"2026-07-16T01:08:51.429Z","0.4.0":"2026-07-17T00:40:35.565Z"},"bugs":{"url":"https://github.com/Avenia-io/avenia-mcp/issues"},"author":{"name":"Avenia"},"license":"MIT","homepage":"https://api-reference.avenia.io","keywords":["avenia","mcp","model-context-protocol","payments","fintech","stablecoin","pix","claude","cursor"],"repository":{"type":"git","url":"git+https://github.com/Avenia-io/avenia-mcp.git"},"description":"Official MCP server for the Avenia public API. Connect Claude Code, Cursor, Zed, and other MCP clients to the Avenia platform.","maintainers":[{"name":"avenia","email":"tech@avenia.io"}],"readme":"Avenia MCP Server![](\"./assets/logo.png\")
\n\n\n[](https://api-reference.avenia.io)\n[](LICENSE)\n\n**Up-to-date Avenia APIs, docs, and integration guides for AI agents.**\n\nThe official [Model Context Protocol](https://modelcontextprotocol.io/) server for [Avenia](https://avenia.io) — borderless payments infrastructure linking Latin America to the world. It gives AI agents live access to Avenia's integration guides, ready-made flows, endpoint specs with request schemas, and authentication guidance — so they can discover services, retrieve the right guide, and generate accurate integration code without relying on stale training data.\n\n> Zero-setup: add the hosted endpoint **`https://mcp.avenia.io/mcp`** as a remote connector (docs & specs, no credentials). Or install locally with a single `npx` command to run live operations — defaults to **sandbox**.\n\n## What This MCP Server Does\n\nThis MCP server plugs AI assistants (claude.ai, Cursor, Claude Code, Claude Desktop, Codex, Zed, and any other MCP-compatible client) directly into the Avenia platform. It exposes 66 API tools — one per public API endpoint — plus 6 documentation tools (list/read guides, list/get flows, list/describe endpoints) that let an assistant:\n\n- Create and manage **sub-accounts** and **accesses** for your organization\n- Move money via **tickets**: Pix pay-ins, PIX / wire pay-outs, FX conversions, and on-chain stablecoin transfers\n- Get **fixed-rate quotes** with full markup-fee control (BRL, USD, EUR, ARS, USDC, USDT, BRLA, and more)\n- Manage **beneficiaries**: wallets + BRL / USD / EUR / ARS bank accounts\n- Run **KYC** flows (Level 1 API, Web SDK, W8-BEN) and track attempts\n- Handle **documents**, **webhooks** (register / update / delete / inspect delivery attempts), and **email notifications**\n- Administer **API keys** with programmatic rotation\n\nFull list: run `listTools` from any MCP client once connected, or see the [API reference](https://api-reference.avenia.io).\n\n## Two ways to use it\n\nThe server has two modes — and the first needs **no credentials**:\n\n- **Explore / learn to integrate (no API key):** install it and ask your assistant how to integrate. It reads Avenia's guides and step-by-step flows bundled in the server (and can fetch the platform public key). Perfect for a first look, with zero setup.\n- **Run live operations (with API key):** add an Avenia API key and the assistant can execute quotes, Pix, FX conversions, on-chain transfers, KYC, etc. Without a key, only these live tools are unavailable — the docs, flows and guides all still work.\n\n**Accounts & API keys (only needed for live operations):**\n\nAvenia accounts are **provisioned by the Avenia team** — there is no self-service sign-up. Contact your Avenia representative to get set up.\n\nAPI keys are **not** created in a dashboard. You create them via the API, behind MFA: log in → enable MFA → create a key with your own RSA public key (the key is returned encrypted to you, then you decrypt it locally). The easiest path is to let your AI assistant walk you through it — connect the MCP (it works keyless) and run the **`/avenia_flow_create_api_key`** prompt. Reference: the [Integration Guide](https://integration-guide.avenia.io) (API Keys / MFA sections). Use a **sandbox** key while testing.\n\n**Dependencies:**\n\n- [Node.js](https://nodejs.org/en/download) v20 or newer (`node -v`) — ships with `npx`, which is all you need for the install below. `git` is only required if you build from source.\n\n## Installation\n\n### Hosted endpoint — zero install (docs & specs only)\n\nAdd **`https://mcp.avenia.io/mcp`** as a remote MCP connector (claude.ai → Settings → Connectors, or any client that supports Streamable HTTP). No install, no credentials — the assistant gets the guides, flows and endpoint specs to answer questions and generate integration code. Live operations are not executable on this endpoint; install locally (below) for those.\n\nNo local install step either — your MCP client runs the server on demand with `npx`. The configs below include an API key for live operations; **to only explore the docs and flows, just omit the `AVENIA_API_KEY` line** and the server runs keyless.\n\n### Claude Desktop — one-click bundle (no terminal)\n\nPrefer zero setup? Download the latest **`.mcpb`** bundle from the [Releases page](https://github.com/Avenia-io/avenia-mcp/releases/latest) and open it — Claude Desktop installs it and shows a form to (optionally) paste your API key and pick the environment. Leave the key blank to browse docs and flows; add it to run live operations. Note: `.mcpb` bundles don't auto-update — grab the latest on each release.\n\n### Claude Code\n\n```bash\nclaude mcp add --transport stdio avenia \\\n --env AVENIA_API_KEY=your-api-key-here \\\n --env AVENIA_ENV=sandbox \\\n -- npx -y @avenia-io/mcp-client\n```\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"avenia\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@avenia-io/mcp-client\"],\n \"env\": {\n \"AVENIA_API_KEY\": \"your-api-key-here\",\n \"AVENIA_ENV\": \"sandbox\"\n }\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"avenia\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@avenia-io/mcp-client\"],\n \"env\": {\n \"AVENIA_API_KEY\": \"your-api-key-here\",\n \"AVENIA_ENV\": \"sandbox\"\n }\n }\n }\n}\n```\n\n### Codex\n\n```bash\ncodex mcp add avenia \\\n --env AVENIA_API_KEY=your-api-key-here \\\n --env AVENIA_ENV=sandbox \\\n -- npx -y @avenia-io/mcp-client\n```\n\nOr add to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.avenia]\ncommand = \"npx\"\nargs = [\"-y\", \"@avenia-io/mcp-client\"]\n\n[mcp_servers.avenia.env]\nAVENIA_API_KEY = \"your-api-key-here\"\nAVENIA_ENV = \"sandbox\"\n```\n\n> [!TIP]\n> `npx -y @avenia-io/mcp-client` always fetches the latest published version. Pin a specific version with `@avenia-io/mcp-client@x.y.z`.\n\n\nFrom source (for contributors)
\n\n```bash\ngit clone https://github.com/Avenia-io/avenia-mcp.git\ncd avenia-mcp\nnpm install\nnpm run build\n```\n\nThen point your client at the built entrypoint: replace `npx -y @avenia-io/mcp-client` in any config above with `node /absolute/path/to/avenia-mcp/dist/index.js` (absolute path — `~` is not expanded by most MCP clients).\n\n \n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `AVENIA_API_KEY` | live ops only | — | API key from the Avenia dashboard. Sent as `X-API-Key`. Omit to run keyless (docs, flows & guides work; live tools return a \"credential required\" message). |\n| `AVENIA_BEARER_TOKEN` | alt. | — | Short-lived JWT from a login flow. Sent as `Authorization: Bearer`. |\n| `AVENIA_ENV` | | `sandbox` | `sandbox` or `production`. |\n| `AVENIA_API_BASE_URL` | | derived | Override the base URL (advanced). |\n| `AVENIA_TIMEOUT_MS` | | `60000` | Per-request HTTP timeout. |\n| `AVENIA_LOG_LEVEL` | | `info` | `silent` / `error` / `info` / `debug` — logs go to stderr. |\n\n## Example Prompts\n\nOnce configured, ask your AI assistant:\n\n```\n\"Get me a fixed-rate quote for sending R$ 10,000 via Pix to USDC on Polygon\"\n\n\"List all tickets from the last 7 days that are still pending\"\n\n\"Create a BRL beneficiary named 'Fornecedor ACME' with Pix key contato@acme.com.br\"\n\n\"Show me my current balances and daily limits\"\n\n\"Register a webhook at https://mysite.com/hook for TICKET events\"\n\n\"Create a sub-account for customer João Silva and send me the sub-account ID\"\n\n\"What's the KYC status of sub-account sub_xxxxxxxx and what's still pending?\"\n```\n\n> [!TIP]\n> Use `AVENIA_ENV=sandbox` while testing. Everything runs against [sandbox.avenia.io](https://api.sandbox.avenia.io:10952/v2) — no real money, no real customers. Switch to `production` only when you're ready.\n\n> [!NOTE]\n> Sub-account operations accept `subAccountId` as a parameter on most tools. If your assistant doesn't pick it up automatically, mention it explicitly in your prompt (e.g. \"…for sub-account sub_abc123…\").\n\n## Flows & Guides\n\nBeyond the 66 tools, the server exposes two more MCP primitives so assistants can run real integration flows end-to-end:\n\n### Prompts (ready-made flows)\n\nNine curated prompts map the most common integrations to a step-by-step plan. In Claude Code, Claude Desktop and Cursor these appear as slash commands (e.g. `/avenia_flow_pix_to_stablecoin_onchain`). Each takes typed arguments and returns a message the assistant can execute directly.\n\n| Prompt | What it does |\n|---|---|\n| `avenia_flow_pix_to_stablecoin_onchain` | Accept Pix in BRL → convert to USDC/USDT → send on-chain to an external wallet |\n| `avenia_flow_stablecoin_to_pix` | Spend a stablecoin balance → pay out via Pix to a BRL beneficiary |\n| `avenia_flow_kyc_level_1` | Submit individual KYC L1 (API or Web SDK) and poll to approval |\n| `avenia_flow_kyb_level_1_api` | Business KYB Level 1 via API |\n| `avenia_flow_register_webhook` | Register a webhook + verify the first delivery signature |\n| `avenia_flow_sandbox_mock_funds` | Credit mock Pix funds in sandbox for testing |\n| `avenia_flow_create_subaccount_with_kyc` | Create a sub-account and run KYC/KYB on it |\n| `avenia_flow_payout_brcode` | Pay a dynamic Pix BR Code (copia-e-cola) |\n| `avenia_flow_create_api_key` | Guide creating an API key (login → MFA → create key; not a dashboard) |\n\n### Resources (integration-guide docs)\n\nEvery page of the [Integration Guide](https://integration-guide.avenia.io) is exposed as an MCP resource at `avenia-guide://`. The assistant can list all 36 guides via `resources/list` and read any of them on demand via `resources/read`. The server fetches the live page, strips navigation chrome, and returns clean markdown — always up-to-date with the docs site, no stale bundled copies.\n\nRepresentative guides (see `resources/list` for the full catalog):\n\n- `avenia-guide://operations-quotes-and-tickets` — how quotes become tickets\n- `avenia-guide://operations-combinations` — valid currency × payment-method combos\n- `avenia-guide://usecase-pix2stable-onchain` — Pix → stablecoin → on-chain\n- `avenia-guide://webhooks-verifying-authenticity` — verifying webhook signatures with the platform public key\n- `avenia-guide://security-api-keys-management` — API key lifecycle with JWE\n- `avenia-guide://kyc-level-1` / `avenia-guide://kyb-level-1-api` — identity verification flows\n\n## Documentation\n\n- [API Reference](https://api-reference.avenia.io) — full endpoint docs with request/response schemas\n- [Integration Guide](https://api-reference.avenia.io/quickstart) — concepts: tickets, quotes, payment methods, KYC levels\n- [MCP Protocol](https://modelcontextprotocol.io/) — how the underlying protocol works\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/Avenia-io/avenia-mcp/issues)\n- **Email**: [developers@avenia.io](mailto:developers@avenia.io)\n- **Status**: [status.avenia.io](https://status.avenia.io)\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\nMade with ♥ by the [Avenia](https://avenia.io) team.\n","readmeFilename":"README.md"}