> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 服务器

> 通过模型上下文协议暴露的 53 个 OrbitFlare 工具。适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code、Gemini CLI 与 Codex CLI。

OrbitFlare MCP 服务器将针对 Shredstream 优化的 Solana RPC、gRPC 流式传输、专属节点与验证者基础设施暴露为 AI 助手可直接调用的工具。每项能力对应独立工具，具备聚焦的输入模式：无内部动作路由器，无基于结果 ID 的分页套路。

<Tip>
  将 MCP 服务器与 [技能](/cn/agents/skills) 搭配使用效果最佳。技能教智能体 *OrbitFlare 如何工作*；MCP 服务器让它无需离开对话即可实际调用 OrbitFlare。
</Tip>

## 安装

大多数主机使用相同 JSON 结构；仅文件位置不同：

```json theme={null}
{
  "mcpServers": {
    "orbitflare": {
      "command": "npx",
      "args": ["@orbitflare/mcp@latest"],
      "env": {
        "ORBITFLARE_API_KEY": "your-license-key",
        "ORBITFLARE_NETWORK": "mainnet"
      }
    }
  }
}
```

| 主机             | 配置文件位置                                                                                                                           |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）· `%APPDATA%\Claude\claude_desktop_config.json`（Windows） |
| Claude Code    | 运行 `claude mcp add orbitflare -- npx @orbitflare/mcp@latest`，或在项目根目录放置 `.mcp.json`                                               |
| Cursor         | `~/.cursor/mcp.json`（全局）或 `<project>/.cursor/mcp.json`                                                                           |
| Gemini CLI     | `~/.gemini/settings.json`（全局）或 `<project>/.gemini/settings.json`                                                                 |
| Windsurf       | `~/.codeium/windsurf/mcp_config.json`                                                                                            |
| VS Code        | 取决于扩展（Continue、Cline、GitHub Copilot 代理模式）                                                                                        |

**Codex CLI** 在 `~/.codex/config.toml`（或 `<project>/.codex/config.toml`）使用 TOML：

```toml theme={null}
[mcp_servers.orbitflare]
command = "npx"
args = ["@orbitflare/mcp@latest"]
```

### 获取许可证密钥

在 [orbitflare.com](https://orbitflare.com) 注册，从控制台 **Licenses（许可证）** 部分复制许可证密钥。免费方案提供 10 RPS，足以立即开始构建。

若不想将密钥写入主机配置，可不设置该环境变量，并在对话中调用 `setApiKey`：

> 将我的 OrbitFlare API 密钥设为 `xxxx-xxxx-xxxx`。

## 配置

| 环境变量                          | 用途                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `ORBITFLARE_API_KEY`          | RPC 许可证密钥（作为 JSON-RPC 的 `?api_key=`）                                                                          |
| `ORBITFLARE_LICENSE_KEY`      | `ORBITFLARE_API_KEY` 的别名                                                                                      |
| `ORBITFLARE_CUSTOMER_API_KEY` | 客户 API v2 密钥（`X-ORBIT-KEY` 标头）。未设置时回退到 `ORBITFLARE_API_KEY`                                                   |
| `ORBITFLARE_NETWORK`          | `mainnet`（默认）或 `devnet`                                                                                       |
| `ORBITFLARE_RPC_URL`          | 可选显式 RPC 端点 URL（覆盖区域/网络）。适用于专属节点。                                                                             |
| `ORBITFLARE_BEARER_TOKEN`     | 客户 API 的 Bearer 令牌。由 `pollDeviceToken` / `verifyWalletSignature` 自动填充，并持久化到 `~/.orbitflare/mcp-session.json`。 |

所有值均可在运行时通过 `setApiKey` 工具覆盖，便于切换网络或固定区域而无需重启主机。

### 区域端点

默认使用 `mainnet`（自动路由）。要固定区域，请通过 `setApiKey` 使用以下之一：`ash`、`ny`、`la`、`slc`、`ams`、`fra`、`lon`、`dub`、`siau`、`tok`、`sgp`。

## 工具

共 53 个工具，按领域分组。每个工具可独立调用。

### RPC 读取

| 工具                                  | 作用                             |
| ----------------------------------- | ------------------------------ |
| `getBalance`                        | 公钥的 SOL 余额，以 lamports 与 SOL 表示 |
| `getAccountInfo`                    | 完整账户信息，可用时含 `jsonParsed` 解码    |
| `getMultipleAccounts`               | 单次调用批量最多 100 个账户               |
| `getProgramAccounts`                | 程序拥有的账户（热门程序需过滤器与 dataSlice）   |
| `getTokenAccountsByOwner`           | 钱包拥有的全部 SPL 代币账户               |
| `getTokenAccountBalance`            | 指定 SPL 代币账户余额                  |
| `getTokenSupply`                    | SPL mint 总供应量                  |
| `getTransaction`                    | 按签名解析的交易                       |
| `getSignaturesForAddress`           | 最近签名（通过 `before` / `until` 分页） |
| `getBlock`                          | 某槽位的区块元数据与交易                   |
| `getSlot`                           | 当前槽位                           |
| `getEpochInfo`                      | 纪元号、槽位索引、每纪元槽位数、进度             |
| `getNetworkStatus`                  | 健康、版本、身份与槽位一次返回                |
| `getLatestBlockhash`                | 最新区块哈希 + lastValidBlockHeight  |
| `getFeeForMessage`                  | 已编译消息的 lamport 费用              |
| `getMinimumBalanceForRentExemption` | 免租金最小 lamports                 |
| `getStakeActivation`                | 质押账户的生效/未生效 lamports 与状态       |
| `getRecentPrioritizationFees`       | 优先费用样本 + P50/P75/P90/P99 分位数   |
| `simulateTransaction`               | 模拟交易；返回日志与消耗单元                 |
| `sendTransaction`                   | 提交已签名的 base-64 交易              |

### 账户、资料与套餐

| 工具              | 作用                             |
| --------------- | ------------------------------ |
| `setApiKey`     | 为会话存储 RPC 或客户 API 密钥，可选切换网络/区域 |
| `getProfile`    | 已认证用户资料 + 账户余额                 |
| `updateProfile` | 更新姓名、邮箱、支付钱包                   |
| `listLicenses`  | 账户下全部 RPC 许可证                  |
| `listRpcPlans`  | 可用套餐目录与定价                      |

### 身份验证（设备码 + 钱包质询）

| 工具                       | 作用                                           |
| ------------------------ | -------------------------------------------- |
| `requestDeviceCode`      | 启动设备授权流程；返回 `verification_uri` + `user_code` |
| `pollDeviceToken`        | 轮询完成；成功时自动存储 Bearer 令牌                       |
| `revokeToken`            | 注销 / 清除 Bearer 令牌                            |
| `requestWalletChallenge` | 获取 Solana 钱包的一次性质询字符串                        |
| `verifyWalletSignature`  | 通过签名登录已有账户                                   |
| `registerWithWallet`     | 通过钱包签名创建新账户                                  |

### API 密钥与许可证

| 工具                     | 作用                        |
| ---------------------- | ------------------------- |
| `listApiKeys`          | 列出全部 API 密钥（掩码显示）         |
| `createApiKey`         | 创建新 API 密钥（完整密钥**仅返回一次**） |
| `regenerateApiKey`     | 按 id 轮换（旧密钥立即失效）          |
| `deleteApiKey`         | 永久删除 API 密钥               |
| `addLicenseIp`         | 在 IP 模式许可证上白名单 IP         |
| `removeLicenseIp`      | 移除已白名单 IP                 |
| `regenerateLicenseKey` | 轮换许可证的 RPC 密钥             |

### 计费

| 工具                | 作用                             |
| ----------------- | ------------------------------ |
| `prepareTopUp`    | 构建未签名的 USDC 充值交易               |
| `confirmTopUp`    | 提交已签名充值；OrbitFlare 链上校验后记入余额   |
| `listInvoices`    | 分页发票列表                         |
| `purchaseRpcPlan` | 使用账户余额购买或 `validateOnly` 仅校验套餐 |

### 流式传输、质押、兑换

| 工具                      | 作用                                                     |
| ----------------------- | ------------------------------------------------------ |
| `subscribeTransactions` | 为 OrbitFlare CLI 生成可用的 Jetstream 或 Yellowstone gRPC 配置 |
| `getStakeInfo`          | OrbitFlare 验证者身份、投票账户、佣金、预估 APY、可选奖励计算器                |
| `getSwapQuote`          | Jupiter Metis 路由报价（自动解析 `SOL` / `USDC` / `USDT` 符号）    |

### 钱包与写入

| 工具                       | 作用                                                     |
| ------------------------ | ------------------------------------------------------ |
| `generateKeypair`        | 生成 Ed25519 密钥对，可选持久化到 `~/.orbitflare/mcp-keypair.json` |
| `loadKeypair`            | 从 base58 密钥或 Solana CLI 密钥文件加载                         |
| `clearKeypair`           | 从会话移除（并可从磁盘移除）                                         |
| `getWalletAddress`       | 返回已加载钱包地址                                              |
| `signMessage`            | 对任意消息进行 Ed25519 签名（utf8 / base58 / base64）             |
| `buildSolTransfer`       | 构建转账 SOL 的未签名版本化交易                                     |
| `buildStakeDelegation`   | 构建委托给 OrbitFlare 投票账户（或任意投票账户）的未签名交易                   |
| `signAndSendTransaction` | 使用会话密钥对签名，经 OrbitFlare RPC 广播                          |

## 流程

### 身份验证（设备码）

<Steps>
  <Step title="请求设备码">
    `requestDeviceCode` 返回 `verification_uri` + `user_code`。模型会向你展示。
  </Step>

  <Step title="在浏览器中批准，然后轮询">
    `pollDeviceToken { device_code }` 按 `interval` 秒重复直至成功。Bearer 令牌自动存储并用于后续客户 API 调用。
  </Step>

  <Step title="退出登录">
    `revokeToken` 清除 Bearer 令牌。
  </Step>
</Steps>

### 身份验证（钱包）

<Steps>
  <Step title="加载密钥对">
    `generateKeypair`（新建）或 `loadKeypair`（来自 base58 / Solana CLI 文件）。
  </Step>

  <Step title="请求质询">
    `requestWalletChallenge { wallet_address }`。
  </Step>

  <Step title="签名并验证">
    `signMessage { message: <challenge> }`，然后 `verifyWalletSignature`（已有账户）或 `registerWithWallet`（新账户）。
  </Step>
</Steps>

### 钱包发送

<Steps>
  <Step title="加载密钥对">
    `generateKeypair` 或 `loadKeypair`。
  </Step>

  <Step title="构建转账">
    `buildSolTransfer { recipient, amountSol }` 返回 base64 未签名交易。
  </Step>

  <Step title="签名并广播">
    `signAndSendTransaction { transaction }` 使用会话密钥对签名、广播，并返回签名与 Solscan 链接。
  </Step>
</Steps>

### 充值

<Steps>
  <Step title="准备充值">
    `prepareTopUp { amount, wallet_address }` 返回 base64 未签名 USDC 转账 + memo。
  </Step>

  <Step title="签名">
    通过 `signAndSendTransaction` 使用已加载钱包签名，或在外部签名。
  </Step>

  <Step title="确认">
    `confirmTopUp { transaction: <signed-base64> }`。OrbitFlare 链上验证后记入余额。
  </Step>
</Steps>

## 资源

服务器将 OrbitFlare 文档暴露为 MCP 资源，模型可按需拉取当前文档：

| URI                                | 页面               |
| ---------------------------------- | ---------------- |
| `orbitflare://docs/index`          | 文档索引（`llms.txt`） |
| `orbitflare://docs/quickstart`     | 快速入门             |
| `orbitflare://docs/authentication` | 认证、端点、速率限制、连接限制  |
| `orbitflare://docs/products`       | 产品与定价            |
| `orbitflare://docs/rpc-http`       | HTTP RPC 参考      |
| `orbitflare://docs/jetstream`      | Jetstream 流式传输   |
| `orbitflare://docs/yellowstone`    | Yellowstone gRPC |
| `orbitflare://docs/staking`        | 验证者质押            |
| `orbitflare://docs/metis-swap`     | Metis Swap API   |
| `orbitflare://docs/cli`            | OrbitFlare CLI   |
| `orbitflare://docs/customer-api`   | 客户 API v2        |

## 系统提示

预置的系统 / 开发者提示位于 [`system-prompts/orbitflare/`](https://github.com/orbitflare/orbitflare-mcp/tree/main/system-prompts/orbitflare) 目录：

* `claude.system.md`：适用于 Claude 的简洁系统提示
* `openai.developer.md`：适用于 OpenAI 模型的简洁开发者消息
* `full.md`：长篇运营手册（认证流程、充值、严格护栏）

将其中一个放入主机配置，可为模型提供何时选用何种工具的端到端指导。

## 试用

安装后，模型会自动选择合适工具：

> 「`Gh9ZwEm…` 的 SOL 余额是多少？」

> 「显示 `7xKXt…` 最近 20 笔交易。」

> 「触碰涉及 Raydium 的账户时，当前有竞争力的优先费用是多少？」

> 「构建从法兰克福流式传输 Jupiter swap 交易的 Yellowstone gRPC 配置。」

> 「以 0.3% 滑点报价 1 SOL → USDC。」

> 「OrbitFlare 验证者投票账户是什么？250 SOL 每年约赚多少？」

## 源码

* MCP 服务器：[github.com/orbitflare/orbitflare-mcp](https://github.com/orbitflare/orbitflare-mcp)
* npm：[`@orbitflare/mcp`](https://www.npmjs.com/package/@orbitflare/mcp)