Molpha MCP

Molpha MCP

一个 Model Context Protocol (MCP) 服务，让 AI Agent 能获取已签名的 Molpha 预言机数据、将其发布到 Solana，并为 EVM 和 Starknet 构建验证器调用数据。

Molpha 会将 HTTP API 响应转换为阈值签名载荷，可在 Solana、EVM 和 Starknet 上进行验证。此服务将这一工作流作为 MCP 工具提供，签名由本地、Privy 或 Turnkey 钱包处理；在 mcp.molpha.io 上则由你自己的钱包处理。

警告

此版本面向 Solana Devnet 和 Sepolia 验证器网络。请将其视为测试网软件，而非生产环境的安全边界。写入工具会消耗 SOL；除非启用试运行模式，否则轮次工具可能会消耗订阅配额，或为 x402 轮次支付 USDC。

快速开始

有两种推荐的连接方式：

	mcp.molpha.io	本地（stdio）
安装	无需安装：将 URL 添加到客户端	npx、Node.js 24 或更高版本
签名者	你自己的钱包。服务不持有密钥。	由服务持有的本地密钥对、Privy 或 Turnkey
订阅轮次	使用 SIWX 登录，然后调用 execute_subscription_round	调用 execute_subscription_round
支出限额	钱包自身的策略	服务中的试运行锁和每日限额
最适合	快速上手、使用自带钱包的 Agent	无人值守的 Agent、私有 API 数据源

mcp.molpha.io

无需安装，也无需交出密钥。将 URL 添加到客户端即可。

Claude Code：

claude mcp add --transport http molpha https://mcp.molpha.io/mcp

Cursor（.cursor/mcp.json）：

{ "mcpServers": { "molpha": { "url": "https://mcp.molpha.io/mcp" } } }

读取工具可直接使用。此服务没有自己的钱包，因此请指定所用的钱包：describe_feed 和 get_latest_value 使用 submitter，get_x402_status 使用 payer。

任何需要签名的操作都会返回待你自己的钱包签名的内容，因此每项此类操作都需要在一次签名的前后调用两三个工具：

操作	工具，按顺序排列	钱包签署的内容
订阅轮次	begin_session → complete_session → execute_subscription_round	一条文本消息，每个会话签一次
x402 轮次	prepare_x402_round → execute_x402_round	一笔尚未广播的 USDC 转账
Solana 提交	prepare_submit_attestation → send_signed_transaction	提交交易

此处不提供 autoSubmit、dryRun 和 encryptSecrets。请在钱包自身的策略中设置支出限额；处理私有 API 数据时，请使用本地服务。

使用钱包登录（SIWX）

在 mcp.molpha.io 上进行订阅轮次时，需要通过登录会话授权：钱包会签署一条 Sign-In-With-X 文本消息（x402 的 sign-in-with-x 扩展的 Solana 形式），网关随后会签发一个短时有效的 bearer token。该消息不是交易，也不会转移资金。

步骤	调用	结果
1	describe_access({ address, owner? })	钱包是订阅的 owner 还是 delegate，以及相应限额
2	begin_session({ address, owner? })	待签署的 message 和不透明的 challenge
3	钱包签署 message	对其精确 UTF-8 字节进行 Ed25519 签名
4	complete_session({ challenge, signature })	sessionToken 及其 expiresAt
5	execute_subscription_round({ sessionToken, apiConfig, signaturesRequired, chains })	已签名的证明和验证器参数

• 谁可以登录。 订阅所有者，或所有者通过 add_delegate 添加的委托人。委托人需将所有者的地址作为 owner 传入。
• 如何签名。 按照原样签署返回的消息：原始 UTF-8，不加前缀或封装，也不加尾随换行符。签名可以是 base58、base64 或 hex。solana sign-offchain-message 会封装文本，因此会被拒绝并返回 invalid_signature。
• Token 的用途。 它是一个凭证，只对应一个钱包和一个网关，默认有效期为 30 分钟，且绝不会超过订阅期限。它只用于识别调用方：网关每次执行轮次时都会从链上重新读取订阅和委托人信息，因此无论已有多少个 Token，remove_delegate 都会立即终止访问。Token 只会经过此服务，不会被存储或记录。
• 所需条件。 GET /v1/info 中 sessionAuth: true 的网关。否则，begin_session 会返回 sessions_unavailable，但 x402 轮次仍可使用。

完整操作指南（含签名示例、委托人设置、网关路由和错误代码）请参阅 docs/integration.md。

本地（stdio）

服务在你的计算机上运行并持有签名者，因此一次工具调用即可执行一轮或提交到 Solana；MOLPHA_DRY_RUN 会让所有写入操作保持为预览，直到你将其关闭。

需要 Node.js 24 或更高版本。无需克隆或构建。

1. 先了解情况，无需钱包。 只读：功能、提供方、sourceId、价格、馈送值。

claude mcp add molpha -- npx -y @molpha/[email protected] --read-only

2. 使用测试网钱包进行构建。 将签名者设置写入 .env 文件（参见设置），然后检查配置。doctor 会打印一份可直接粘贴到客户端的配置，密钥会保留为占位符：

npx -y @molpha/[email protected] doctor

类似这样的配置会让所有写入操作都保持为预览（MOLPHA_DRY_RUN=true）：

claude mcp add molpha -e SIGNER_BACKEND=keychain -e KEYCHAIN_BACKEND=privy -e PRIVY_APP_ID='<privy-app-id>' -e PRIVY_APP_SECRET='<privy-app-secret>' -e PRIVY_WALLET_ID='<privy-wallet-id>' -e PRIVY_WALLET_ADDRESS='<base58-solana-address>' -e MOLPHA_DRY_RUN=true -- npx -y @molpha/[email protected]

3. 仅在确有需要时才支出。 为钱包注资，然后在服务配置中设置 MOLPHA_DRY_RUN=false。完整指南（含 Cursor、VS Code、Codex 和 Claude Desktop）请参阅 docs/integration.md。

未配置签名者时，服务会以只读模式启动，仅提供读取工具（get_capabilities 中的 runLevel: "read-only"）。--read-only 或 SIGNER_BACKEND=none 可强制启用此模式。

工具

工具	访问权限	描述
get_capabilities	读取	运行级别、程序 ID、注册表版本、节点、网关、链、验证器地址、x402 限额和来源付款策略。
derive_source_id	读取、本地	推导 apiConfig 的 sourceId（方法）。不发起交易，也不需要钱包。
describe_feed	读取	读取 Solana Feed 中 (sourceId, signaturesRequired, submitter) 对应的内容，以及签名者的订阅状态。
get_latest_value	读取	读取 Solana Feed 账户中存储的最新认证值。
describe_access	读取	查询钱包是否为订阅所有者或委托人，以及套餐和委托人的限额。
get_x402_status	读取	估算下一轮 x402 的费用，显示付款去向，并读取付款方的 USDC 余额和剩余每日预算。
list_providers	读取	网关集成的数据提供方及其支持的流程（提供方）。
get_provider	读取	单个提供方的流程、披露信息和现成 Feed，每项均包含完整的 apiConfig 和 sourceId。
quote_source_payment	读取	通过一次未付款请求，为设有付费墙的数据源估价，包含最高总费用。
execute_subscription_round	消耗配额	执行一轮由 USDC 订阅付款的请求；返回已签名的证明及验证器参数。autoSubmit: true 会在同一次调用中结算 Solana。
execute_x402_round	消耗 USDC	通过 x402 按请求付费，执行一轮请求；输出相同。
build_verifier_calldata	读取、本地	构建 EVM/Starknet 验证器地址和 verify() 调用参数。仅生成 Calldata，不会验证任何内容。
submit_attestation	写入	向 Solana 提交已签名的证明。可直接接收轮次工具的原始输出。

在 mcp.molpha.io 上，单次调用的轮次和提交工具会变为 prepare/sign/execute 组合（见上文）。每个工具都会返回 structuredContent 并附带 MCP 注解；请参阅结构化输出和注解。有关容差模式聚合和完整配置表，请参阅 docs/reference.md。

轮次时间。 轮次按固定的 100 ms 时钟周期运行。同一时钟周期内对同一个 Feed（相同来源和法定人数）的请求会共用一轮，因此每个 Feed 每秒最多运行 10 轮；对于某个 Feed，每个钱包每个时钟周期最多运行一轮：同一时钟周期内的第二次请求会收到 HTTP 409，轮次工具会在下一个时钟周期重试，之后才会失败并返回 round_conflict。请参阅轮次时间。

设置

适用于本地服务。

签名者。 将设置写入 .env 文件，并使用 doctor 检查。它会输出可直接粘贴到客户端的配置，机密信息保留为占位符。请使用专用的测试网钱包。

SIGNER_BACKEND=memory
OWNER_KEYPAIR=/absolute/path/to/owner-keypair.json
SOLANA_RPC=https://api.devnet.solana.com
MOLPHA_DRY_RUN=true

Privy 和 Turnkey 的设置请参阅 docs/reference.md 和 .env.example。

npx -y @molpha/[email protected] doctor

试运行锁定。 MOLPHA_DRY_RUN=true 会将 execute_subscription_round、execute_x402_round 和 submit_attestation 锁定为仅预览模式。带有 dryRun: false 的调用会被拒绝，并返回 dry_run_locked，因此启用正式运行需要更改服务配置，不能通过单次工具调用实现。

订阅。 订阅会扣除 USDC，因此该功能不会放在 MCP 工具中，而是作为 CLI 命令运行，并使用相同的签名者配置。--max-price-usdc 是以 USDC 最小单位（6 位小数）为单位的上限；移除 --dry-run 即可订阅，也可以使用 extend 延长订阅。

npx -y @molpha/[email protected] provision subscribe --plan Basic --max-price-usdc 20000000 --dry-run

客户端。 每个客户端都会通过 npx 启动本地服务。Claude Code、Cursor、VS Code、Codex 和 Claude Desktop 的代码片段位于 docs/integration.md，可直接编辑的副本位于 examples；Claude Desktop 用户可以安装附在每个版本中的 molpha-mcp.mcpb 软件包。

示例提示词

发现。 使用 Molpha 检查当前的预言机能力。总结注册表版本、节点数量、链、网关和验证器地址。不要执行任何写入操作。

推导。 使用 JSON 路径 $.price，为 https://api.example.com/v1/finalized/price 推导 Molpha sourceId。向我展示规范 JSON 和 sourceId。不要发送交易。

获取。 对该数据源运行一轮订阅，为 EVM 链使用 3 个签名。总结数值、时间戳、注册表版本和验证器调用。将签名证明视为信任锚，而不只是数值本身。

提供方。 列出集成的数据提供方，描述 TickerLayer 的 btcusd 数据流，并为 Solana 使用 3 个签名运行该数据流，严格按给定内容传递 apiConfig。

检查支出。 为 3 个签名调用 get_x402_status。告诉我价格、付款去向，以及在我授权 execute_x402_round 前我的 USDC 余额。

发布。 如果我提供了更新的签名证明，请使用 dryRun: true 预览 submit_attestation，说明具体写入内容，并在提交前等待我的确认。

请使用返回稳定且可独立复现数据的公共端点：实时行情端点在不同预言机节点上可能不同，无法达到法定人数。

工作原理

flowchart LR
    Client["MCP client"] <-->|"stdio / HTTP"| Server["Molpha MCP server"]
    Server --> Guardrails["Dry-run · daily caps · spend caps"]
    Server --> Signer["Signer adapter<br/>local · Privy · Turnkey"]
    Server --> SDK["Molpha SDK / x402 client"]
    SDK --> Gateway["Molpha gateway"]
    Gateway <--> Nodes["Oracle node quorum"]
    SDK <--> Solana["Solana program<br/>feeds · subscriptions"]
    Gateway --> Artifact["Threshold-signed attestation"]
    Artifact --> Server
    Server --> Args["EVM / Starknet verifier args,<br/>or submit_attestation on Solana"]

该服务是一个适配器和策略边界，而不是新的事实来源。预言机节点会独立获取已提交的 API 配置，并在达到法定人数后生成一个聚合签名；该服务会返回这个自包含的签名产物。使用方只有在根据其注册表版本验证签名负载后，才能信任其中的数值。

开发

git clone https://github.com/molpha/mcp.git
cd mcp
npm ci
cp .env.example .env
npm run build

使用 node /absolute/path/to/mcp/dist/src/server.js 将客户端指向构建后的服务。

npm run dev          # start from TypeScript
npm run typecheck && npm test && npm run build   # run before opening a pull request
npm run gen:install  # rewrite the generated install snippets in the docs and examples
npm run smoke:pack   # pack the tarball and run it with npx over stdio (needs network)
npm run pack:mcpb    # build the Claude Desktop bundle from an allowlist

@molpha/sdk 固定为确切版本，并从 npm 注册表解析；如需尝试本地检出版本，请运行 npm install ../sdk，且不要提交生成的结果。安装代码片段由 src/install-config.ts 生成：请编辑渲染器，而不是生成的文本，因为生成文件不是最新版本时，npm test 会失败。

版本管理和发布使用 Changesets：如果拉取请求更改了已发布行为，请运行 npx changeset。合并到 main 后，release.yml 会创建一个“Version Packages”拉取请求；该请求合并后，会将 @molpha/mcp 发布到 npm（可信发布，无令牌），并将 server.json 发布到 MCP 注册表。

欢迎提交错误报告和内容聚焦的拉取请求。对于安全问题，请使用 GitHub 的私密漏洞报告，不要公开提交问题。

文档

• 集成指南：按客户端安装、支出、使用自己的钱包登录（SIWX），以及自行运行 HTTP 服务
• 参考文档：sourceId、容差模式、x402、提供方、配置、签名者
• Molpha 协议文档
• 客户端配置示例和 MCPB 清单

许可证

基于 MIT License 发布。