内容
<h1>艾维尼亚 MCP 服务器<img src="./assets/logo.png" align="right" width="102"/></h1>
[](https://api-reference.avenia.io)
[](LICENSE)
**最新的艾维尼亚 API、文档和使用指南，适用于 AI 代理。**
[模型上下文协议](https://modelcontextprotocol.io/) 的官方服务器，为 [艾维尼亚](https://avenia.io) 提供服务 — 连接拉丁美洲与世界的无边界支付基础设施。它为 AI 代理提供实时的访问权限，获取艾维尼亚的集成指南、现成的流程、端点规格和身份验证指南 — 这样它们就可以发现服务、获取正确的指南并生成准确的集成代码，而无需依赖过时的训练数据。
> 零设置：添加托管端点 **`https://mcp.avenia.io/mcp`** 作为远程连接器（文档和规格，无需凭证）。或使用单个 `npx` 命令本地安装以运行实时操作 — 默认情况下为 **沙盒环境**。
## MCP 服务器的作用
该 MCP 服务器将 AI 助手（claude.ai、Cursor、Claude Code、Claude Desktop、Codex、Zed 和其他任何兼容 MCP 的客户端）直接连接到艾维尼亚平台。它公开了 66 个 API 工具 — 每个公共 API 端点一个 — 以及 6 个文档工具（列出/读取指南、列出/获取流程、列出/描述端点），让助手可以：
- 创建和管理 **子账户** 和 **访问权限**，适用于您的组织
- 通过 **票据** 转移资金：Pix 支付、PIX / 电汇支付、外汇兑换和链上稳定币转移
- 获取 **固定汇率报价**，并具有完全的 markup-fee 控制权（BRL、USD、EUR、ARS、USDC、USDT、BRLA 等）
- 管理 **受益人**：钱包 + BRL / USD / EUR / ARS 银行账户
- 运行 **KYC** 流程（1 级 API、Web SDK、W8-BEN）并跟踪尝试
- 处理 **文档**、**网络钩子**（注册 / 更新 / 删除 / 检查交付尝试）和 **电子邮件通知**
- 管理 **API 密钥**，并具有编程轮换功能
完整列表：从任何连接的 MCP 客户端运行 `listTools`，或查看 [API 参考](https://api-reference.avenia.io)。
## 使用它的两种方式
服务器有两种模式 — 第一种模式 **不需要凭证**：
- **探索 / 学习集成（无 API 密钥）：** 安装它并询问您的助手如何集成。它读取艾维尼亚的指南和服务器中捆绑的逐步流程（并且可以获取平台的公共密钥）。适用于首次查看，零设置。
- **运行实时操作（带有 API 密钥）：** 添加艾维尼亚 API 密钥，助手可以执行报价、Pix、外汇兑换、链上转账、KYC 等。没有密钥，只有这些实时工具不可用 — 文档、流程和指南仍然可用。
**账户和 API 密钥（仅适用于实时操作）：**
艾维尼亚账户由 **艾维尼亚团队提供** — 没有自助注册。联系您的艾维尼亚代表来设置。
API 密钥 **不是** 在仪表板中创建的。您通过 API 创建它们，在 MFA 后面：登录 → 启用 MFA → 使用您自己的 RSA 公钥创建密钥（密钥以加密形式返回给您，然后您在本地解密它）。最简单的方法是让您的 AI 助手引导您完成 — 连接 MCP（它无需密钥即可工作）并运行 **`/avenia_flow_create_api_key`** 提示。参考：[集成指南](https://integration-guide.avenia.io)（API 密钥 / MFA 部分）。在测试期间使用 **沙盒** 密钥。
**依赖项：**
- [Node.js](https://nodejs.org/en/download) v20 或更新版本（`node -v`）— 随 `npx` 捆绑提供，安装下面内容所需。`git` 仅在您从源代码构建时需要。
## 安装
### 将艾维尼亚 MCP 连接到 Claude（远程连接器，无需 API 密钥）
艾维尼亚的文档连接器为 Claude 提供实时的 API 指南、集成流程和端点规格访问权限，直接在对话中。它 **仅限读取，不需要凭证** — 您的账户中没有任何内容被访问。
连接器 URL： **`https://mcp.avenia.io/mcp`**
在 Claude 上（免费、专业和最大计划 — 网页、桌面应用或 Cowork）：
1. 打开 Claude 并转到 **设置 → 连接器** （或 **自定义 → 连接器**）
2. 点击 **添加自定义连接器**
3. 粘贴 `https://mcp.avenia.io/mcp` 并确认（不需要 OAuth 字段）
4. 完成 — 艾维尼亚的文档工具可用于 Claude
在 **Claude 团队/企业** 上，只有所有者/管理员可以为组织启用连接器（组织设置 → 添加自定义连接器，相同的 URL）；成员则自动看到它。任何其他支持 Streamable HTTP 传输的 MCP 客户端也适用。
需要实时操作，而不仅仅是文档？使用下面的本地安装 — 您的 API 密钥永远不会离开您的机器。
<details>
<summary><strong>Português</strong></summary>
艾维尼亚的文档连接器为 Claude 提供实时的 API 指南、集成流程和端点规格访问权限，直接在对话中。它 **仅限读取，不需要凭证**。
连接器 URL： `https://mcp.avenia.io/mcp`
在 Claude 上（免费、专业和最大计划）：打开 **设置 → 连接器** （或 **自定义 → 连接器**）→ **添加自定义连接器** → 粘贴 URL 并确认。在 Claude 团队/企业中，只有所有者/管理员为组织启用连接器。需要实时操作，而不仅仅是文档？使用本地安装包（`npx -y @avenia-io/mcp-client` 或 Claude 桌面版的 `.mcpb`），其中 API 密钥永远不会离开您的机器。
</details>
在本地安装步骤中，您的 MCP 客户端使用 `npx` 按需运行服务器。下面配置中包含用于实时操作的 API 密钥；**如果省略 `AVENIA_API_KEY` 行**，则服务器运行无密钥（文档、流程和指南有效；实时工具返回“需要凭证”的消息）。
### Claude 桌面版 — 一键式安装包（无需终端）
喜欢零设置？从 [发布页面](https://github.com/Avenia-io/avenia-mcp/releases/latest) 下载最新的 **`.mcpb`** 安装包并打开它 — Claude 桌面版安装它并显示一个表单，允许您（可选）粘贴您的 API 密钥并选择环境。留空密钥以浏览文档和流程；添加它以运行实时操作。注意：`.mcpb` 安装包不会自动更新 — 每次发布时请获取最新的安装包。
### Claude Code
```bash
claude mcp add --transport stdio avenia \
--env AVENIA_API_KEY=您的-api-密钥-在此 \
--env AVENIA_ENV=沙盒环境 \
-- npx -y @avenia-io/mcp-client
```
### 游标
添加到 `~/.cursor/mcp.json`：
```json
{
"mcpServers": {
"avenia": {
"command": "npx",
"args": ["-y", "@avenia-io/mcp-client"],
"env": {
"AVENIA_API_KEY": "您的-api-密钥-在此",
"AVENIA_ENV": "沙盒环境"
}
}
}
}
```
### Claude 桌面版
添加到您的 Claude 桌面版配置文件：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"avenia": {
"command": "npx",
"args": ["-y", "@avenia-io/mcp-client"],
"env": {
"AVENIA_API_KEY": "您的-api-密钥-在此",
"AVENIA_ENV": "沙盒环境"
}
}
}
}
```
### Codex
```bash
codex mcp add avenia \
--env AVENIA_API_KEY=您的-api-密钥-在此 \
--env AVENIA_ENV=沙盒环境 \
-- npx -y @avenia-io/mcp-client
```
或添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.avenia]
command = "npx"
args = ["-y", "@avenia-io/mcp-client"]
[mcp_servers.avenia.env]
AVENIA_API_KEY = "您的-api-密钥-在此"
AVENIA_ENV = "沙盒环境"
```
> [!TIP]
> `npx -y @avenia-io/mcp-client` 始终获取最新的发布版本。使用 `@avenia-io/mcp-client@x.y.z` 固定特定版本。
<details>
<summary><strong>从源代码（适用于贡献者）</strong></summary>
```bash
git clone https://github.com/Avenia-io/avenia-mcp.git
cd avenia-mcp
npm install
npm run build
```
然后将您的客户端指向构建的入口点：用 `node /absolute/path/to/avenia-mcp/dist/index.js` 替换上述配置中的 `npx -y @avenia-io/mcp-client` （绝对路径 — `~` 不被大多数 MCP 客户端扩展）。
</details>
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|---|---|---|---|
| `AVENIA_API_KEY` | 仅实时操作 | — | 来自艾维尼亚仪表板的 API 密钥。作为 `X-API-Key` 发送。省略以无密钥运行（文档、流程和指南有效；实时工具返回“需要凭证”的消息）。 |
| `AVENIA_BEARER_TOKEN` | 替代 | — | 登录流程的短期 JWT。作为 `Authorization: Bearer` 发送。 |
| `AVENIA_ENV` | | `沙盒环境` | `沙盒环境` 或 `生产环境`。 |
| `AVENIA_API_BASE_URL` | | 派生 | 覆盖基本 URL（高级）。 |
| `AVENIA_TIMEOUT_MS` | | `60000` | 每请求 HTTP 超时。 |
| `AVENIA_LOG_LEVEL` | | `info` | `silent` / `error` / `info` / `debug` — 日志输出到 stderr。 |
## 示例提示
配置完成后，询问您的 AI 助手：
```
“给我一个将 R$ 10,000 通过 Pix 转换为 USDC 并发送到 Polygon 上的外部钱包的固定汇率报价。”
“列出过去 7 天内仍处于待处理状态的所有票据。”
“为名为‘Fornecedor ACME’的 BRL 受益人创建 Pix 密钥 contato@acme.com.br。”
“显示我的当前余额和每日限额。”
“在 https://mysite.com/hook 为 TICKET 事件注册一个网络钩子。”
“为客户 João Silva 创建一个子账户，并将子账户 ID 发送给我。”
“子账户 sub_xxxxxxxx 的 KYC 状态是什么？还有什么 pending？”
> [!TIP]
> 在测试期间使用 `AVENIA_ENV=沙盒环境`。所有操作都在 [sandbox.avenia.io](https://api.sandbox.avenia.io:10952/v2) 上运行 — 无需真实资金，无需真实客户。仅在您准备好时切换到 `生产环境`。
> [!NOTE]
> 子账户操作在大多数工具上接受 `subAccountId` 作为参数。如果您的助手无法自动获取它，请在提示中明确提及它（例如“…适用于子账户 sub_abc123…”）。
## 流程和指南
除了 66 个工具外，服务器还公开了两个额外的 MCP 原语，以便助手可以端到端地运行真正的集成流程：
### 提示（现成流程）
九个精选提示将最常见的集成映射到一步一步的计划。在 Claude Code、Claude 桌面版和 Cursor 中，这些提示显示为斜杠命令（例如 `/avenia_flow_pix_to_stablecoin_onchain`）。每个提示接受键入的参数并返回助手可以直接执行的消息。
| 提示 | 它执行的操作 |
|---|---|
| `avenia_flow_pix_to_stablecoin_onchain` | 接受 BRL 中的 Pix → 转换为 USDC/USDT → 发送到链上的外部钱包 |
| `avenia_flow_stablecoin_to_pix` | 消费稳定币余额 → 通过 Pix 支付给 BRL 受益人 |
| `avenia_flow_kyc_level_1` | 提交个人 KYC 1 级（API 或 Web SDK）并轮询到批准 |
| `avenia_flow_kyb_level_1_api` | 通过 API 进行企业 KYB 1 级 |
| `avenia_flow_register_webhook` | 注册网络钩子 + 验证第一个交付签名 |
| `avenia_flow_sandbox_mock_funds` | 在沙盒环境中提供模拟 Pix 资金用于测试 |
| `avenia_flow_create_subaccount_with_kyc` | 创建子账户并在其上运行 KYC/KYB |
| `avenia_flow_payout_brcode` | 支付动态 Pix BR 代码（复制和粘贴） |
| `avenia_flow_create_api_key` | 引导创建 API 密钥（登录 → MFA → 创建密钥；不是仪表板） |
### 资源（集成指南文档）
[集成指南](https://integration-guide.avenia.io) 的每一页都作为 MCP 资源以 `avenia-guide://<id>` 形式公开。助手可以通过 `resources/list` 列出所有 36 个指南，并在需要时通过 `resources/read` 读取任意一个。服务器获取实时页面，剥去导航栏并返回干净的 Markdown — 始终与文档站点保持最新，无需过时的捆绑副本。
代表性指南（参见 `resources/list` 获取完整目录）：
- `avenia-guide://operations-quotes-and-tickets` — 报价如何变为票据
- `avenia-guide://operations-combinations` — 有效的货币 × 支付方式组合
- `avenia-guide://usecase-pix2stable-onchain` — Pix → 稳定币 → 链上
- `avenia-guide://webhooks-verifying-authenticity` — 使用平台公钥验证网络钩子签名
- `avenia-guide://security-api-keys-management` — 具有 JWE 的 API 密钥生命周期
- `avenia-guide://kyc-level-1` / `avenia-guide://kyb-level-1-api` — 身份验证流程
## 文档
- [API 参考](https://api-reference.avenia.io) — 具有请求/响应模式的完整端点文档
- [集成指南](https://api-reference.avenia.io/quickstart) — 概念：票据、报价、支付方式、KYC 级别
- [MCP 协议](https://modelcontextprotocol.io/) — 底层协议的工作原理
## 支持
- **问题：** [GitHub 问题](https://github.com/Avenia-io/avenia-mcp/issues)
- **电子邮件：** [developers@avenia.io](mailto:developers@avenia.io)
- **状态：** [status.avenia.io](https://status.avenia.io)
## 许可证
该项目根据 [MIT 许可证](LICENSE) 授权。
由 [艾维尼亚](https://avenia.io) 团队用 ♥ 制作。
