OneSource MCP

@one-source/mcp

适用于 OneSource 的统一 MCP 服务 — 在单个服务中提供 91 个工具，涵盖区块链数据、实时链上查询、Deepstate 市场数据、The Standard Reserve 和 REST API 文档。

什么是 MCP？ Model Context Protocol 可让 AI 助手调用工具并访问数据源。此服务将 OneSource 区块链 API 及其文档作为工具提供。

快速开始

Claude Code

claude mcp add onesource -- npx -y @one-source/mcp@latest

Claude Desktop / Cursor

添加到 MCP 配置中：

{
  "mcpServers": {
    "onesource": {
      "command": "npx",
      "args": ["-y", "@one-source/mcp@latest"]
    }
  }
}

任意 MCP 客户端（stdio）

npx -y @one-source/mcp@latest

HTTP 服务（可自托管）

npx -y @one-source/mcp@latest --http
npx -y @one-source/mcp@latest --http --port=8080

然后将 MCP 客户端连接到 http://localhost:3000/（或你的 --port 值，例如上方第二个示例中的 8080）。

运行状况检查：GET http://localhost:3000/health（替换为你的端口）。

工具（97 个）

区块链 API — 实时链上数据（12 个工具）

工具	描述
1s_allowance_live	检查 ERC20 授权额度
1s_contract_info_live	通过 ERC165 检测合约类型
1s_erc1155_balance_live	通过 RPC 查询 ERC1155 余额
1s_erc20_balance_live	通过 balanceOf 查询 ERC20 余额
1s_erc20_transfers_live	通过 eth_getLogs 查询 ERC20 Transfer 日志
1s_erc721_tokens_live	ERC721 代币枚举
1s_events_live	通过 eth_getLogs 查询事件日志
1s_multi_balance_live	ETH + 多种 ERC20 余额
1s_nft_metadata_live	通过 tokenURI 查询 NFT 元数据
1s_nft_owner_live	通过 ownerOf 查询 NFT 所有者
1s_total_supply_live	代币总供应量
1s_tx_details_live	通过 RPC 查询交易 + 收据

区块链 API — 链上实用工具（13 个工具）

仅限 RPC。

工具	描述
1s_block_by_number	通过 RPC 按区块编号查询区块详情
1s_block_number	最新区块编号
1s_chain_id	EIP-155 链 ID
1s_contract_code	合约字节码
1s_ens_resolve	ENS 名称/地址解析
1s_estimate_gas	Gas 估算
1s_network_info	链 ID、区块编号、Gas 价格
1s_nonce	交易计数
1s_pending_block	来自内存池的待处理区块
1s_proxy_detect	代理合约检测
1s_simulate_call	模拟 eth_call
1s_storage_read	读取存储槽
1s_tx_receipt	交易收据

支付（2 个工具）

工具	描述
1s_payment_mode	查看或切换四种模式下的支付通道 + 方案：x402-exact / x402-batch（Base 上的 USDC）和 mpp-charge / mpp-session（Tempo 上的 USDC.e / pathUSD）。batch 和 session 会开启一个可为多次调用提供资金的通道。
1s_refund	按需取回开放支付通道中未使用的存款 — 适用于 x402 batch 通道（Base）和 MPP session 凭证通道（Tempo）

Deepstate 市场数据（10 个工具）

Deepstate 是 Robinhood Chain（链 ID 为 4663）上的链上订单簿协议。这些工具用于读取市场数据，包括订单簿、交易、K 线、统计数据、做市商分析以及 Gas／深度分析。它们是同一 API 上的普通工具，不需要 network 参数——始终使用 Robinhood Chain——并且与其他所有工具一样需要付费：使用 API 密钥、x402 或 MPP。自 DGP-3 迁移（2026-09-22）以来，做市商奖励按市场发放，而非单一固定代币——请始终查看 1s_ds_markets 中某个市场的 reward_token，不要默认它是 DEEP。

工具	描述
1s_ds_markets	列出此 API 提供的 Deepstate 市场（订单簿），包括每个市场的 slug、代币布局、池／路由器地址、status 和 reward_token
1s_ds_book	市场的订单簿快照——买单按价格降序排列，卖单按价格升序排列，并显示每个价位的挂单数量
1s_ds_trades	市场的交易记录，按时间从新到旧排列——包含每笔成交的价格、数量、方向和区块
1s_ds_candles	指定时间周期的市场 OHLCV K 线
1s_ds_stats	市场滚动 24 小时／7 天／30 天的交易量和价格变动，以及最新成交价
1s_ds_makers	市场的做市商分析数据——订单簿顶部的停留时间、挂单名义金额、成交次数／频率，以及已赚取的做市商奖励（奖励代币按市场确定——请参阅 1s_ds_markets 中的 reward_token）
1s_ds_cost_to_quote	市场挂单和撤单所消耗的 Gas，按时间分组
1s_ds_depth_history	市场深度热力图——随时间变化的各价位挂单数量
1s_ds_token_2deep	2DEEP 的供应量、上限、流通量、奖励池和捐赠基金余额、迁移负债以及池价格——链上实时数据
1s_ds_migration	自 DGP-3（2026-09-22）以来 DEEP／STATE 兑换为 2DEEP 的进度：总量、数量、剩余量和每日序列

除 1s_ds_markets 外，每个 Deepstate 工具都需要 book 参数：市场的规范大写 slug（例如 NVDA-USDG）或其 32 字节 book_id。请先调用 1s_ds_markets 获取完整列表。

The Standard Reserve（49 个工具）

The Standard Reserve 是 Robinhood Chain（链 ID 为 4663）上的链上中央银行协议。这些工具用于读取 OneSource 索引并提供的已部署合约状态，每个响应都包含 basis、as_of_block 和 serving_state。1s_std_addresses 和 1s_std_genesis_live 免费；此处其他所有工具与本 API 的其余工具一样需要付费：使用 API 密钥、x402 或 MPP。若干工具（1s_std_supply、_vaults、_pool、_exit_pressure、_backing、_policy_current）还接受 atBlock 参数，可读取截至过去某个区块的状态，而非最新状态。

工具	描述
1s_std_addresses	TSR 合约和池的已验证注册表，每个条目均附有验证状态。免费，无需付款。
1s_std_auction_days	许可证或章程拍卖的逐日历史：开盘价／底价／收盘价、已售数量与供应数量、售罄所需时间；许可证日还会列出购买次数、不同章程数、平均和总支付金额，以及每笔交易的购买量分布
1s_std_auction_sales	许可证或章程拍卖的近期销售记录，按时间从新到旧排列：买家、单价、数量和区块。可按类型筛选，使用 before/limit 翻页
1s_std_auctions_current	每日许可证拍卖和章程拍卖的当前状态：价格、底价、今日已售／剩余数量、阶段和最近一笔销售
1s_std_backing	储备支持情况：金库 ETH 余额、储备资产持有量、金库的 Uniswap v4 仓位，以及每个 STANDARD 对应的 ETH 支持额，分为三种口径：仅计入金库 ETH、加上协议自有流动性，以及按储备自身池价计入全部储备资产（USDG 按 $1 计）。可查询当前值、历史记录或指定过去区块的状态
1s_std_branch_auction_live	Branch 许可证拍卖的原始最新状态：阶段、价格、今日已售／剩余数量和近期销售速度
1s_std_branches_doi	Branch 许可证拍卖的发行天数，以及立即购买与等待的对比表
1s_std_branches_summary	TSR 活跃 Branch 的汇总：数量、每个 Branch 每日发行量，以及以发行天数计的许可证价格
1s_std_buyback_readiness	收缩金库回购刻度的准备情况：本刻度的 ETH 容量、限制因素、冷却时间、TWAP 偏差和近期执行的刻度
1s_std_candles	ETH/STANDARD 池的 OHLC 价格蜡烛图，以每个 STANDARD 对应的 ETH 计价，并附有交换次数和交易量。设置 tf 指定蜡烛图宽度（1m 至 1d），设置 from/to 指定时间范围
1s_std_charter	按 ID 查询单个章程，或按所有者筛选章程：持有者、Branch 数量、铸造类型、应得产出、Branch 历史、其在一次性章程激励中的份额（所有者可在响应返回的截止日期前领取），以及其在每次 launchpad 章程空投中的份额
1s_std_decision_branch	综合查询：现在是否应该购买 Branch／许可证。汇总发行天数、许可证成本与章程拍卖的对比、近期拍卖历史、政策展望、待处理的治理变更，以及某个 Branch 在过去 launchpad 章程空投中获得的收益（历史数据，并非预测）
1s_std_decision_bid	综合查询：以此最高价格挂出许可证拍卖买单后，何时可能成交、前面有多少买单和许可证，以及（提供 charter_id 时）该章程待领取的 STANDARD 和额度是否足以满足买单。成交需要任何人另行发送一笔交易；响应会说明这一点并提供测得的成交历史。接受 max_unit_price；count 和 charter_id 为可选参数
1s_std_decision_charter	综合查询：现在是否应该买入新章程。汇总章程拍卖状态、成本最低的许可证获取路径、发行天数、支持率、持有人集中度，以及某个 Branch 在过去 launchpad 章程空投中获得的收益（历史数据，并非预测）
1s_std_decision_exit	综合查询：现在是否应该退出章程的 Branch。汇总退出报价、费用曲线、费用预测、税费计划、池状态、政策展望、待处理的治理变更、全部退出将放弃的未领取激励，以及关闭后将释放的章程空投，并附有 noteOwner 警告
1s_std_decision_hold	综合查询：是否应该继续持有 STANDARD。汇总政策展望、发行余量、待处理的治理变更、税费计划、回购准备情况和休眠状态；无需参数
1s_std_decision_plan	在指定期限内模拟三种 Branch 购买策略（保留、择机、积极），除非另行覆盖，否则以实时价格、发行量和许可证成本为初始数据。提供章程 ID 时，会在策略旁边显示 launchpad 空投份额，并将其排除在所有 ETH 结果之外。这是规划工具，并非预测：它绝不会指出哪种策略胜出
1s_std_decision_sbill	综合查询：应如何处理此 S-Bill。到期前：现在退出的支付金额、放弃的溢价，以及假设无人退出时未来每一天的退出费用（推导值）。到期后：赎回支付金额和续存将锁定的利率（推导值），并说明不会自动续存。接受 bill_id
1s_std_decision_stake	综合查询：现在是否应该将此 STANDARD 存入 S-Bill，还是等待。汇总 S-Bill 报价、按钱包检查的额度、存入后立即退出的费用，以及假设无人再存入时 1h／6h／24h 的利率（推导值）。接受 amount；wallet 为可选参数
1s_std_dormancy	已超过可报告休眠期限的钱包，或完整的已追踪钱包列表
1s_std_dormancy_bounties	休眠赏金看板：已超过可报告期限的钱包，按预估赏金从高到低排序
1s_std_epochs	TSR epoch 历史：每个 epoch 的净流量、信号、机制和发行量。使用 before/limit 翻页
1s_std_events	原始解码后的协议事件，可选按 contract_label、event_name、地址、token_id、epoch 或区块／日志游标筛选，并使用 before/limit 翻页
1s_std_exit_fee_curve	退出费用如何随提现规模变化：当前费率，以及按总提现额的 1／5／10／25／50／100% 计算的阶梯费率
1s_std_exit_fee_forecast	按当前速度推算在没有更多提现时退出费用的逐日变化，另列费用降至最低值所需天数，以及每个已记录的提现日离开费用窗口的准确时刻
1s_std_exit_pressure	退出压力读数及相应的结算费率。可查询当前值、历史记录或指定过去区块的状态
1s_std_exit_quote	关闭章程未关闭的 Branch 时按比例计算的退出报价，并提供指定区块时可实现的 ETH 估算值
1s_std_flow_charters	按发生每次交换时持有章程的钱包分组，列出 ETH/STANDARD 池的买入和卖出。设置 hours 和 limit 指定结果时间范围
1s_std_flow_hourly	ETH/STANDARD 池每小时流入和流出的 ETH 量，以及交换次数。设置 hours 指定回溯时长
1s_std_genesis_live	Genesis 荷兰式铸造的最新统计：阶段、已铸造数量、剩余数量、价格和销售速度。免费。
1s_std_governance_changes	TSR 追踪的 15 个合约的治理／参数变更历史、当前排队的变更、开关状态和 guardian 暂停状态
1s_std_holders_concentration	章程／Branch 所有权集中度：章程分布、主要所有者、HHI（赫芬达尔－赫希曼指数）评分，以及 Genesis 与拍卖群体的划分
1s_std_issuance_runway	对比中央银行发行预算列出累计 STANDARD 发行量、当前流速，以及在状态不变情况下预算耗尽时间的预测
1s_std_license_bids	在同一个区块读取的许可证拍卖所有挂单：竞标者、数量、最高单价、合约是否可以成交、每笔买单的限制条件、过期或可清理标记，以及推导出的有效交叉价格。可按章程、竞标者或可成交状态筛选并排序
1s_std_license_cost	Branch 许可证当前的 ETH 成本，以及章程拍卖是否是达到相同结果的更便宜途径
1s_std_license_headroom	章程今天还能购买多少张 Branch 许可证，并提供实时单价报价阶梯
1s_std_policy_current	当前 epoch 的货币政策：机制、乘数、净流量和双 epoch 信号。可查询当前值或指定过去区块的状态
1s_std_policy_outlook	假设当前 epoch 的净流量正负号持续至结束，在状态不变情况下推算政策乘数和发行率
1s_std_pool	ETH/STANDARD Uniswap v4 池的最新状态：价格、tick、流动性、储备和剩余 launch tax。可查询当前值或指定过去区块的状态
1s_std_protocol_flows	按时间从新到旧排列的协议资金流动：持仓迁移、税款转发、费用回收、团队领取、POL 回购、费用和配对、激励发放，以及由多签持有的储备金库流出的资金；同时列出转移资金的方法和用于标示接收方的 to_label。使用 kind 筛选，使用 cursor 翻页
1s_std_sbills_bills	按 ID 查询单个 S-Bill，或按所有者或状态筛选 S-Bill：本金、溢价、锁定利率、到期时间和结算方式。单个 S-Bill 查询还会返回实时退出和赎回报价
1s_std_sbills_current	当前的 S-Bill 质押条款：各期限的利率及其简单年利率、漂移状态、锁定本金、溢价预算、额度和提前退出费用窗口。利率按期限计算，并非年利率
1s_std_sbills_events	解码后的 S-Bill 合约事件，按时间从新到旧排列：存入、提前退出、赎回、续存、结算、奖励分发、利率变更和管理员变更
1s_std_sbills_quote	将 STANDARD 质押至 S-Bill 的实时报价：将锁定的利率、托管的溢价、存入后的利率，以及额度或暂停状态是否会阻止操作。直接读取合约数据
1s_std_sbills_rate_history	S-Bill 利率变化记录：每次链上利率变更以及定期漂移采样，并标明当时生效的期限长度
1s_std_supply	STANDARD 供应账目：流通量、累计铸造量、按路径累计销毁量、最大供应量和未领取的章程激励（过去区块的值为 null）。可查询当前值、历史记录或指定过去区块的状态
1s_std_tax_schedule	Launch tax-hook 计划：当前买入／卖出税、衰减配置，以及 launch 计划生效期间带标签的预测
1s_std_vaults	扩张金库和收缩金库余额：持有的 WETH 和 STANDARD、协议自有流动性，以及回购容量。可查询当前值、历史记录或指定过去区块的状态
1s_std_wallet	单个钱包持有的所有章程对应的完整 TSR 持仓：待领取收益、退出报价概要、休眠状态、许可证额度、可领取的章程激励，以及可领取和已锁定的章程空投

文档（8 个工具）

无需身份验证。这些工具从服务随附的文档语料库中提供答案，因此不产生费用，即使尚未配置付款方式也能使用。它们与独立的 @one-source/docs-mcp 服务同名，该服务提供相同的语料库。

工具	描述
1s_search_docs	在 OneSource 开发者文档中按关键词搜索
1s_get_api_overview	REST API 涵盖的内容——操作数量、标签、网络和付款协议
1s_list_endpoints	所有 REST 端点及其方法、路径、价格和摘要；可按标签筛选
1s_get_endpoint_reference	单个端点的完整信息——参数、请求正文、响应示例、价格和 curl
1s_search_use_cases	根据任务的自然语言描述查找合适的端点
1s_list_networks	REST API 路由到的网络，以其已发布规范中的声明为准
1s_get_payment_info	价格范围、付款渠道和收款地址；指定端点时提供该端点的信息
1s_get_authentication_guide	如何向 REST API 进行身份验证，以及应选择哪种方法

设置与运维（3 个工具）

无需身份验证。

工具	用途	使用时机
1s_setup_check	**交互式设置与运行状况检查。**逐项引导用户完成两种付款渠道的所有配置选项（身份验证方法、x402、MPP、付款模式、渠道偏好）——每次运行都会引导，即使已经完成配置；此外还会检查版本、身份验证状态、渠道状态和连接情况	首先调用此工具——用于设置、修改配置或排查问题
1s_batch_config	查看或更改付款渠道偏好（自主性、阈值、x402 存款倍率、MPP 会话存款上限、默认模式），并将其持久化保存，以便重启后保留——无需编辑配置	在会话中配置渠道行为
1s_report_bug	向 Slack 报告错误（或在 Slack 不可用时使用 GitHub Issues）	工具出错或用户想要报告问题时

网络

所有区块链 API 工具都接受可选的 network 参数：

网络	描述
ethereum	Ethereum 主网（默认）
sepolia	Ethereum Sepolia 测试网
robinhood	Robinhood Chain，链 ID 为 4663（Arbitrum Orbit L2）——仅限实时 RPC

身份验证

区块链 API 工具需要身份验证。有三种可用方式——如果同时设置了 API 密钥和钱包密钥，API 密钥将优先使用，钱包密钥会被忽略。

**提示：**配置上述任何方式，最快捷的方法是使用 1s_setup_check 工具——它会逐步引导你完成所有选项，并提供一条可直接运行的命令，因此你无需手动编辑环境变量或配置文件。以下手动说明可供参考。

方法	变量	说明
API 密钥	ONESOURCE_API_KEY	调用次数不限，无单次调用费用
x402 微支付	X402_PRIVATE_KEY	通过 Base 上的 USDC 按次付费，无需账户
MPP 微支付	MPP_PRIVATE_KEY	通过 Tempo 上的 USDC.e / pathUSD 按次付费，无需账户

选项 1：API 密钥

1. 前往 app.onesource.io 并创建账户。
2. 通过 Stripe 结账完成 API 密钥订阅。
3. 前往 API Keys 并生成密钥。
4. 复制密钥——它以 sk_ 开头。

Claude Code

claude mcp add onesource -e ONESOURCE_API_KEY=<key> -- npx -y @one-source/mcp@latest

Claude Desktop / Cursor

将 env 区块添加到 MCP 配置中：

{
  "mcpServers": {
    "onesource": {
      "command": "npx",
      "args": ["-y", "@one-source/mcp@latest"],
      "env": {
        "ONESOURCE_API_KEY": "<key>"
      }
    }
  }
}

任意 MCP 客户端（stdio）

ONESOURCE_API_KEY=<key> npx -y @one-source/mcp@latest

添加后，重新加载 MCP 服务并调用 1s_setup_check——在 Current configuration 下，应显示 Active auth method: API key（并显示密钥的前 6 个字符）。

选项 2：x402 微支付

区块链 API 端点通过 x402 使用 Base 上的 USDC 计价。设置 X402_PRIVATE_KEY 后，服务会自动处理付款——工具调用会自动付费并透明重试，Agent 无需进行任何额外操作。

1. 获取 EVM 私钥——从 MetaMask、Coinbase Wallet 或任何 EVM 钱包导出，或者生成一个新的私钥。该密钥是 64 个字符的十六进制字符串。0x 前缀可选，两种格式均可接受。
2. 使用以下任一方法将密钥传递给服务。
3. 重新加载并查找钱包地址——重新加载 MCP 服务，然后调用 1s_setup_check。在 Current configuration 下会列出 x402 (Base) wallet，即根据你的密钥推导出的地址。
4. 向该地址充值 Base 上的 USDC——在 Base 网络上，向 1s_setup_check 显示的地址发送 USDC。几美元（1–5 USDC）足以支付数百次调用。如果你的 USDC 在 Ethereum 主网上，可使用 Base Bridge 进行跨链转移。
5. 验证——调用 1s_network_info，并指定 ethereum。如果返回链数据（区块编号、Gas 价格），则表示 x402 付款已端到端正常运行。

Claude Code

claude mcp add onesource -e X402_PRIVATE_KEY=<key> -- npx -y @one-source/mcp@latest

Claude Desktop / Cursor

将 env 区块添加到 MCP 配置中：

{
  "mcpServers": {
    "onesource": {
      "command": "npx",
      "args": ["-y", "@one-source/mcp@latest"],
      "env": {
        "X402_PRIVATE_KEY": "<key>"
      }
    }
  }
}

任意 MCP 客户端（stdio）

X402_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest

选项 3：MPP 微支付（Tempo）

区块链 API 端点也可通过 MPP 使用 Tempo 网络付款，这是 x402 在 Base 上的替代方案。设置 MPP_PRIVATE_KEY 后，服务会自动处理付款；工具调用会自动付费并透明重试。

1. 获取 EVM 私钥——格式与 x402 相同（64 个字符的十六进制字符串，0x 前缀可选）。导出一个密钥或生成一个新的密钥。
2. 使用以下任一方法将密钥传递给服务。
3. 重新加载并查找钱包地址——重新加载 MCP 服务，然后调用 1s_setup_check。在 Current configuration 下会列出 MPP (Tempo) wallet，即根据你的密钥推导出的地址。
4. 向该地址充值 Tempo 上的 USDC.e 或 pathUSD——几美元即可支付数百次调用。
5. 验证——调用 1s_network_info。如果返回链数据，则表示 MPP 付款已端到端正常运行。

Claude Code

claude mcp add onesource -e MPP_PRIVATE_KEY=<key> -- npx -y @one-source/mcp@latest

Claude Desktop / Cursor

{
  "mcpServers": {
    "onesource": {
      "command": "npx",
      "args": ["-y", "@one-source/mcp@latest"],
      "env": {
        "MPP_PRIVATE_KEY": "<key>"
      }
    }
  }
}

任意 MCP 客户端（stdio）

MPP_PRIVATE_KEY=<key> npx -y @one-source/mcp@latest

默认情况下，MPP 按调用付费（mpp-charge）。如果要连续调用多次，可切换到 Tempo 凭证通道：使用 1s_payment_mode { "mode": "mpp-session" }（或设置 MPP_PAYMENT_MODE=session）——一次存款即可为多次链下调用提供资金；可随时使用 1s_refund 取回未使用的余额，也可在正常关闭时自动结算。

配置文件位置

如果你更愿意直接编辑配置文件，而不是使用 CLI 命令：

客户端	配置文件路径
Claude Code	运行 claude mcp get onesource 查看文件路径
Claude Desktop（macOS）	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop（Windows）	%APPDATA%\Claude\claude_desktop_config.json
Cursor（macOS）	~/.cursor/mcp.json
Cursor（Windows）	%USERPROFILE%\.cursor\mcp.json

使用上方的 JSON 代码块，在 "mcpServers" 中添加 onesource 条目。

替代方案：设置为环境变量

你可以将以下任一变量设置为 shell 或系统环境变量，以替代 env 配置块：export ONESOURCE_API_KEY=<key>（bash/zsh）或 $env:ONESOURCE_API_KEY = "<key>"（PowerShell）。在操作系统层级设置变量，可使其在不同会话间持久生效。

支付通道（可选）

默认情况下，每次付费调用都会签署一笔支付（Base 上使用 x402-exact，Tempo 上使用 mpp-charge）。如果要连续调用多次，可以开启支付通道——一次链上存款即可为多次链下调用提供资金，并统一结算，相比逐次付费更省钱：

• x402（Base）： 使用 1s_payment_mode { "mode": "x402-batch" } 切换到 x402-batch（或设置 X402_PAYMENT_MODE=batch）。首次调用会存入 price × X402_DEPOSIT_MULTIPLIER（默认值为 10）。
• MPP（Tempo）： 使用 1s_payment_mode { "mode": "mpp-session" } 切换到 mpp-session（或设置 MPP_PAYMENT_MODE=session）。首次调用最多存入 MPP_MAX_DEPOSIT（默认值为 1）。

可随时使用 1s_refund 工具取回未使用的余额（两种支付网络均适用）；剩余金额始终可在链上取回。闲置的 x402 通道也会在几小时后自动退款，MPP 会话则会在正常关闭时自动结算。

通过钱包付款时，Agent 启动后会在其系统提示词中收到通道指引，因此它可以代你管理这项操作，无需你手动处理：当 Agent 预计会连续调用多次时，会提议为当前支付网络切换到通道模式，并在结束后提醒你使用 1s_refund。你可以使用 X402_BATCH_PROMPT（ask / auto / off）和 X402_BATCH_THRESHOLD（预计调用多少次算作连续调用；两个支付网络共用此设置）控制其主动程度——请参阅环境变量。1s_setup_check 会报告当前模式、通道是否可用以及所有设置。

安全

切勿将密钥提交到源代码管理中。请使用环境变量、不纳入 git 的 .env 文件，或密钥管理器。

更改任何配置后： 在 Claude Code 中运行 /reload-plugins，或重启 Claude Desktop / Cursor。必须重新加载 MCP 服务，才能读取新的环境变量。

环境变量

必需

设置其中一个即可访问区块链 API 工具。未设置任何密钥时，只能使用无需身份验证的 Setup & Ops 工具。同时设置 API 密钥和钱包密钥时，API 密钥优先。

变量	默认值	描述
ONESOURCE_API_KEY	—	用于 Bearer token 身份验证的 OneSource API 密钥。优先于钱包支付通道。
X402_PRIVATE_KEY	—	用于在 Base 上自动支付 x402 USDC 的 EVM 私钥（64 位十六进制，可选 0x 前缀）。
MPP_PRIVATE_KEY	—	用于在 Tempo 上自动支付 MPP（USDC.e / pathUSD）的 EVM 私钥。

可选 / 高级

所有配置项都有合理的默认值，支付通道模式开箱即用。仅在需要覆盖端点、调整支付通道模式的行为或修改分析设置时才设置这些配置项。也可以在运行时使用 1s_payment_mode 工具切换支付模式。以下支付通道配置项（X402_PAYMENT_MODE、X402_DEPOSIT_MULTIPLIER、MPP_PAYMENT_MODE、MPP_MAX_DEPOSIT、X402_BATCH_PROMPT、X402_BATCH_THRESHOLD）可在会话中通过 1s_batch_config 工具设置并持久化，无需编辑配置或重启；已保存的配置优先于这些环境变量。

变量	默认值	描述
ONESOURCE_BASE_URL	https://api.onesource.io	API 基础 URL。
X402_PAYMENT_MODE	exact	初始 x402 方案：exact（按次支付）或 batch（支付通道）。可在会话中使用 1s_payment_mode 切换。
X402_RPC_URL	Base 默认值	用于在批量模式下提交支付通道存款的 Base RPC 端点。
X402_DEPOSIT_MULTIPLIER	10	批量模式：存款 = 价格 × 此倍数，为每个支付通道提供相应次数的调用资金。未使用的余额可通过 1s_refund 取回。
X402_CHANNEL_DIR	—	用于在重启后保留批量支付通道状态的目录。未设置 = 仅存储在内存中（重启后支付通道会丢失）。
X402_CHANNEL_SALT	zero	批量模式：用于派生起始支付通道 ID 的 32 字节十六进制盐值。支付通道耗尽或退款后，客户端会自动轮换到下一个盐值。
MPP_PAYMENT_MODE	charge	初始 MPP 方案：charge（按次支付）或 session（Tempo 凭证支付通道）。可在会话中使用 1s_payment_mode 切换。
MPP_MAX_DEPOSIT	1	会话模式：每个 Tempo 凭证支付通道锁定的 USDC.e / pathUSD 最大金额。未使用的余额可通过 1s_refund 取回。
MPP_RPC_URL	Tempo 默认值	用于在会话模式下提交支付通道存款的 Tempo RPC 端点。
X402_BATCH_PROMPT	ask	Agent 如何处理切换到支付通道模式（适用于两种支付通道）：ask（切换前确认）、auto（自动切换）或 off（仅在明确要求时切换）。
X402_BATCH_THRESHOLD	5	当会话中预期调用次数达到或超过此值时，Agent 会考虑使用支付通道模式（适用于两种支付通道）。此值仅供参考，Agent 会估算调用次数，不会将其作为严格的运行时计数器。
ONESOURCE_CONFIG_DIR	~/.onesource	存放服务器管理的支付通道配置（batch-config.json）的目录，该配置由 1s_batch_config 写入。
ONESOURCE_ANALYTICS	true	设置为 false 可停用分析功能。
ONESOURCE_ANALYTICS_URL	https://1s-analytics.vercel.app	分析功能的仪表板端点。
ONESOURCE_ANALYTICS_KEY	onesource-mcp	仪表板分析功能的 API 密钥。旧别名 X402_ANALYTICS_KEY 仍可使用，但已弃用。

故障排除

1s_setup_check 显示“Active auth method: none”（区块链工具已锁定） 在 Current configuration 下，“Active auth method: none”表示尚未设置身份验证。设置 ONESOURCE_API_KEY（API 密钥）、X402_PRIVATE_KEY（Base 上的 x402）或 MPP_PRIVATE_KEY（Tempo 上的 MPP）之一；也可以直接运行 1s_setup_check，按提示完成设置。设置任何变量后，都要重新加载 MCP 服务（参见上方说明）。如果密钥仍未传递到服务，请直接将其设置为 shell 环境变量。

设置正确却收到 403 / 使用了错误的密钥 在 shell 配置文件（例如 ~/.zshrc、~/.bash_profile）中设置的密钥，即使没有写入 Claude MCP 配置，也会被 MCP 服务进程读取。在终端中运行 echo $ONESOURCE_API_KEY 进行检查。如果输出的值不是你想要的，可以取消设置（unset ONESOURCE_API_KEY），或在添加服务时显式清除该变量：claude mcp add onesource -e ONESOURCE_API_KEY= -e X402_PRIVATE_KEY=<key> -- npx -y @one-source/mcp@latest。1s_setup_check 会显示当前生效密钥的前 6 个字符，方便你确认服务正在使用哪个密钥。

重新安装后，说明中显示的身份验证方式不正确 在 Claude Code 中运行 /reload-plugins 会重新连接工具，但可能不会刷新大模型看到的系统提示词。如果你切换了身份验证方式（例如从 API 密钥切换到 x402），请完整重启 Claude Code，确保说明反映了新的身份验证方式。

“MCP server onesource already exists”错误 先运行 claude mcp remove onesource，然后使用更新后的配置重新添加。

Windows：npx 需要 cmd /c 包装 Claude Code 的 /doctor 命令可能会对此发出警告。更新 MCP 配置，使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "@one-source/mcp@latest"]。

**npx 卡住且没有输出** 这是正常的 — stdio 模式会等待从 stdin 输入 JSON-RPC。如果你想要一个可以用 curl 访问的 HTTP 服务，请使用 --http。

端口已被占用 指定其他端口：npx -y @one-source/mcp@latest --http --port=8080

注册表发布

此软件包已列入官方 MCP 注册表，使用经过验证的命名空间 io.onesource/mcp，并已列入 Glama。发布新版本时，请更新这两个注册表。

MCP 注册表

首次设置

1. 安装 Go

从 go.dev/dl 下载适用于你平台的安装程序并运行。验证：

go version

2. 安装 mcp-publisher

go install github.com/modelcontextprotocol/registry/cmd/mcp-publisher@latest

如果 Go 模块路径已更改，导致命令失败，请改为从 mcp-publisher GitHub releases 页面直接下载二进制文件。

在 Windows 上，如果无法识别该命令，请将 Go 的 bin 目录添加到 PATH：

$env:PATH += ";$env:USERPROFILE\go\bin"

验证：

mcp-publisher --help

3. DNS 身份验证（已完成）

onesource.io 域名包含用于证明 io.onesource 命名空间所有权的 DNS TXT 记录。此项已配置完成 — 无需重新设置。

该记录位于根域名（onesource.io，而非 _mcp-registry.onesource.io）：

v=MCPv1; k=ed25519; p=7D3U5rufgNXb/lH2MthTRZdDzEGeE7/Jvg8YkiArQc8=

你可以验证其是否能解析：

nslookup -type=TXT onesource.io 8.8.8.8

4. 获取私钥

身份验证需要与 DNS 记录中的公钥对应的 ed25519 私钥，格式为 hex。请向团队负责人索取此密钥 — 它保存在团队的密码管理器 / 密钥库中。

如果需要重新生成密钥对（这会使当前 DNS 记录失效，并需要更新该记录）：

1. 生成新的 ed25519 密钥对（例如，openssl genpkey -algorithm Ed25519 -out key.pem）
2. 提取原始的 32 字节私钥种子并转换为 hex：

 openssl pkey -in key.pem -outform DER | tail -c 32 | xxd -p -c 32

3. 提取用于 DNS TXT 记录的 base64 格式公钥：

 openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64

4. 使用新的公钥更新 onesource.io 上的 DNS TXT 记录：

 v=MCPv1; k=ed25519; p=<base64-public-key>

5. 等待 DNS 传播后再尝试登录。

发布新版本

请使用发布脚本。 通常通过 sre-services 仓库中的协调发布脚本来执行发布 （scripts/release-mcp.mjs——参见 sre-services/RELEASING.md）， 该脚本会按正确顺序完成以下所有步骤，涵盖 @one-source/api-mcp 和 @one-source/mcp，包括更新 server.json 和执行 mcp-publisher publish。上述首次设置仍是执行注册表步骤的前提。以下手动步骤是注册表专用修复 或脚本无法运行时的备用方案。

每次发布新的 npm 版本时，都要更新 MCP Registry：

1. 发布到 npm（注册表会验证软件包是否存在，因此必须先完成此步骤）：

 npm run build
 npm publish --access public

2. 更新 server.json——将两个 version 字段设为与新的 npm 版本一致：

 {
   "version": "x.y.z",
   ...
   "packages": [{ "version": "x.y.z", ... }]
 }

package.json 中的 mcpName 字段必须为 "io.onesource/mcp"，并且必须与 server.json 中的 name 字段一致。此项已设置，请勿移除。 3. 进行身份验证（令牌会过期，因此每次都要执行）：

 mcp-publisher login dns --domain onesource.io --private-key <ed25519-hex-private-key>

4. 发布到注册表：

 mcp-publisher publish

5. 验证：

 curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=onesource"

Glama

Glama 每天会自动与 GitHub 仓库同步。发布后无需手动操作，只需确保更改已推送到 develop（默认分支）。仓库根目录中的 glama.json 文件用于控制所有权。认领服务后，可在 Glama 管理面板中手动重新同步。

隐私政策

使用此扩展会连接到 OneSource API。有关数据处理方式的详情，请参阅 OneSource 隐私政策。

许可证

Apache 2.0——详情请参阅 LICENSE。