IBM Granite via x402

@three-ws/ibm-x402-mcp

通过 MCP 按次付费使用 IBM Granite AI——聊天、编程、嵌入、分析和预测，使用 Solana 上的 USDC 结算。无需 IBM 账户。

安装 · 快速开始 · 工具 · 支付流程 · 要求 · three.ws

---

一个模型上下文协议服务，通过 x402 支付协议将 IBM Granite 基础模型作为按次付费的工具提供。最终用户每次调用均使用 Solana 上的 USDC 付费——无需拥有自己的 IBM Cloud 账户。服务运营者提供 IBM 凭据（WATSONX_*）和用于收款的 Solana 钱包（MCP_SVM_PAYMENT_ADDRESS）；调用者只需提供 USDC。一个免费工具（ibm_granite_getting_started）会在任何付款前介绍价格和流程。

由 three.ws 构建。由社区构建，与 IBM 无关。

工作原理

1. MCP 客户端（Claude Desktop、Claude Code、Cursor 或 Agent）连接到此服务。
2. 客户端调用一个工具，例如 ibm_granite_chat。
3. 如果没有 x402 支付载荷，服务会返回一个 402 PaymentRequired 信封，其中列出 USDC 价格和 Solana 收款地址。
4. 客户端签署一笔 Solana USDC 转账，并在 _meta["x402/payment"] 中附上付款后重试。
5. 服务通过中介方验证并结算付款，调用 IBM watsonx.ai，并在 _meta["x402/payment-response"] 中附上结算收据后返回结果。

支持 x402 的 MCP 客户端会自动处理此流程。

安装

npm install @three-ws/ibm-x402-mcp

可直接使用 npx 运行（无需安装）：

MCP_SVM_PAYMENT_ADDRESS=<your-solana-wallet> \
WATSONX_API_KEY=<ibm-api-key> \
WATSONX_PROJECT_ID=<watsonx-project-id> \
npx @three-ws/ibm-x402-mcp

也可以全局安装，以便在 PATH 中使用 ibm-x402-mcp 命令：

npm install -g @three-ws/ibm-x402-mcp

快速开始

运行此进程的人是运营者：如果未配置收款地址和 IBM 凭据（WATSONX_API_KEY、WATSONX_PROJECT_ID），服务会在启动时立即失败。调用正在运行的服务只需 USDC——无需 IBM 账户。使用 Claude Code 时，只需一条命令：

claude mcp add ibm-granite-x402 \
  -e MCP_SVM_PAYMENT_ADDRESS=your-solana-wallet \
  -e WATSONX_API_KEY=your-ibm-api-key \
  -e WATSONX_PROJECT_ID=your-watsonx-project-id \
  -- npx -y @three-ws/ibm-x402-mcp

也可以将此服务接入 MCP 客户端配置（claude_desktop_config.json、Cursor 的 mcp.json）：

{
	"mcpServers": {
		"ibm-x402": {
			"command": "npx",
			"args": ["-y", "@three-ws/ibm-x402-mcp"],
			"env": {
				"MCP_SVM_PAYMENT_ADDRESS": "your-solana-wallet-address",
				"WATSONX_API_KEY": "your-ibm-cloud-api-key",
				"WATSONX_PROJECT_ID": "your-watsonx-project-id"
			}
		}
	}
}

使用 MCP Inspector 检查工具列表：

npx -y @modelcontextprotocol/inspector npx @three-ws/ibm-x402-mcp

工具

工具	功能	价格
ibm_granite_getting_started	概览、价格和 x402 支付流程。无需付款或 IBM 账户。	免费
ibm_granite_chat	通过 IBM Granite 提供对话式 AI（默认模型为 ibm/granite-3-8b-instruct）。	$0.02 USDC
ibm_granite_code	生成、审查、重构、解释、测试和编写代码文档。	$0.025 USDC
ibm_granite_embed	用于 RAG、搜索和聚类的批量文本嵌入（1–64 条文本）。	$0.005 USDC
ibm_granite_analyze	结构化文档分析：实体、情绪、风险标记、摘要和后续步骤。	$0.04 USDC
ibm_granite_forecast	通过 IBM Granite TTM（Tiny Time Mixer）进行零样本时间序列预测。	$0.05 USDC

每个工具都是只读的模型推理调用——不会修改你计算机上的任何内容，也不会修改任何账户中的内容——并声明了 MCP 工具注解（readOnlyHint、openWorldHint、idempotentHint），以便客户端在付款前判断副作用。

输入参数

ibm_granite_getting_started — section（可选：overview（默认，全部内容）/ pricing / payment / tools / setup）。

ibm_granite_chat — messages（必填：1–50 个 { role, content } 对；角色为 system/user/assistant，内容不超过 32,000 个字符），model（默认 ibm/granite-3-8b-instruct），max_new_tokens（1–4096，默认 1024），temperature（0–2，默认 0.7）。

ibm_granite_code — task（必填：generate/review/refactor/explain/test/document），prompt（必填，不超过 16,000 个字符：generate 时为描述，其他任务时为代码），language，context（不超过 4,000 个字符）。

ibm_granite_embed — inputs（必填：1–64 条文本，每条不超过 8000 个字符），model。

ibm_granite_analyze — document（必填），analysis_type（general/contract/financial/technical/medical/sentiment，默认 general），language。

ibm_granite_forecast — timestamps（必填：64–1024 个 ISO-8601 时间戳，间隔均匀，按时间从早到晚排列），values（必填：64–1024 个数字，长度相同），freq（必填：pandas 频率，例如 1h、1D），prediction_length（1–96），label。

调用示例

// ibm_granite_chat
{
  "messages": [
    { "role": "system", "content": "You are an expert data engineer." },
    { "role": "user", "content": "Design a lakehouse schema for IoT sensor telemetry." }
  ],
  "max_new_tokens": 1024,
  "temperature": 0.7
}

// ibm_granite_code
{ "task": "review", "prompt": "def calculate_roi(revenue, cost): return revenue / cost", "language": "Python" }

// ibm_granite_embed
{ "inputs": ["enterprise data governance", "cloud-native AI pipeline", "real-time analytics"] }

// ibm_granite_analyze
{ "document": "This Software License Agreement is entered into between...", "analysis_type": "contract" }

// ibm_granite_forecast  (timestamps/values must be 64–1024 points; abbreviated here)
{ "timestamps": ["2025-01-01T00:00:00Z", "...", "2025-03-05T00:00:00Z"], "values": [12500, "...", 13200], "freq": "1D", "prediction_length": 14, "label": "daily_revenue_usd" }

支付流程

此服务使用 x402 protocol 进行小额支付：

1. 客户端在未付款的情况下调用工具 → 返回包含 USDC 金额和 Solana 地址的 402 PaymentRequired。
2. 客户端构建并签署 Solana USDC 转账交易。
3. 客户端在 _meta["x402/payment"] 中附上已签名的交易并重试。
4. 服务通过配置的支付协调器（默认为 PayAI）验证并完成结算。
5. 服务调用 IBM watsonx.ai，并在 _meta["x402/payment-response"] 中返回结果（结算收据）。

MCP Client (Claude Desktop / Cursor / agent)
       │  tools/call (with x402 payment in _meta)
       ▼
ibm-x402-mcp (stdio MCP server)
       │  verify + settle USDC on Solana
       ├──► x402 facilitator (default https://facilitator.payai.network)
       │
       │  inference call with IAM Bearer token
       └──► IBM watsonx.ai (us-south.ml.cloud.ibm.com)
                 └── IBM Granite 3 8B Instruct / Embedding / TTM

要求

• Node.js >= 20。
• 用于接收 USDC 的 Solana 钱包地址（MCP_SVM_PAYMENT_ADDRESS）。
• IBM Cloud 凭据：API 密钥（创建 API 密钥）和 watsonx.ai 项目 ID（Project → Manage → General → Project ID），或部署空间 ID。

环境变量

变量	必需	默认值
MCP_SVM_PAYMENT_ADDRESS	是	—（别名：X402_PAY_TO_SOLANA、X402_PAY_TO）
WATSONX_API_KEY	是	—
WATSONX_PROJECT_ID	是（或 WATSONX_SPACE_ID）	—
WATSONX_SPACE_ID	可替代 WATSONX_PROJECT_ID	—
WATSONX_URL	否	https://us-south.ml.cloud.ibm.com
WATSONX_MODEL_ID	否	ibm/granite-3-8b-instruct
WATSONX_CODE_MODEL_ID	否	ibm/granite-3-8b-instruct
WATSONX_EMBED_MODEL_ID	否	ibm/granite-embedding-278m-multilingual
WATSONX_FORECAST_MODEL	否	ibm/granite-ttm-512-96-r2
WATSONX_TIMEOUT_MS	否	90000
X402_FEE_PAYER_SOLANA	否	three.ws 费用支付方
X402_FACILITATOR_URL	否	https://facilitator.payai.network
X402_FACILITATOR_TOKEN	否	—（私有协调器的 Bearer 令牌）
X402_ASSET_MINT_SOLANA	否	Solana USDC 的标准铸币地址

区域主机：us-south、eu-de、eu-gb、jp-tok、au-syd、ca-tor——例如 https://eu-de.ml.cloud.ibm.com。

错误

每种失败状态都会明确说明，不会静默回退：

状态	现象	处理方法
启动时缺少环境变量	进程会退出，并输出一行 configuration error: …，指出缺少的变量（MCP_SVM_PAYMENT_ADDRESS、WATSONX_API_KEY 或 WATSONX_PROJECT_ID/WATSONX_SPACE_ID）。	设置变量并重启。
未付款就调用收费工具	返回一个 x402 PaymentRequired 信封，其中列明 USDC 价格和收款地址——这不是错误，而是付款流程的第 1 步。	付款后重试（支持 x402 的客户端会自动完成此操作）。
付款无效或金额不足	协调器会拒绝验证，并返回新的 PaymentRequired 信封；不会运行推理，也不会结算资金。	根据列出的接受条件重新签名。
IBM 端故障	工具结果为 { "ok": false, "error": "watsonx_error", "message": "…", "status": … }——可能是 IAM 身份验证失败（WATSONX_API_KEY 无效）、模型错误或 watsonx.ai 超时（WATSONX_TIMEOUT_MS，默认 90 s）。	消息中会说明 IBM 返回的原因；请检查凭据、项目 ID 和区域。
意外的服务端故障	工具结果为 { "ok": false, "error": "internal_error", "message": "…" }。	重试；如果问题仍然存在，请提交 issue。
启动时无法连接协调器	stderr 中会输出一行 facilitator init warning: …；服务仍会启动，并在首次收费调用时延迟重试。	检查与 X402_FACILITATOR_URL 的连接。

ibm_granite_getting_started 始终免费，也不会联系 IBM 或协调器——可用它在付款前检查服务是否正常。

相关内容

• @three-ws/ibm-watsonx-mcp — 使用你自己的 IBM Cloud 凭据调用相同的 IBM Granite 工具（不使用 x402，也无需按次付款）。

链接

• 主页：https://three.ws
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，详见 LICENSE

---

_{属于 three.ws SDK 套件的一部分 — 3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}