IBM Granite x402 Remote

@three-ws/ibm-x402-mcp

MCP 経由で従量課金制の IBM Granite AI を利用できます。チャット、コード、埋め込み、分析、予測に対応し、料金は Solana 上で USDC により支払われます。IBM アカウントは不要です。

インストール · クイックスタート · ツール · 支払いの流れ · 要件 · three.ws

---

Model Context Protocol サーバーです。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、またはエージェント）がこのサーバーに接続します。
2. クライアントがツール（例：ibm_granite_chat）を呼び出します。
3. x402 支払いペイロードがない場合、サーバーは USDC 価格と Solana の受取アドレスを提示する 402 PaymentRequired エンベロープを返します。
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 なら、次の 1 つのコマンドで実行できます。

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（必須：{ role, content } のペアを1～50個。ロールは system／user／assistant、content は最大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（必須：ISO-8601 形式で64～1024個、一定間隔、古い順）、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 キー（作成はこちら）と 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。

エラー

すべての失敗状態は明示されます。暗黙的なフォールバックはありません。

状態	表示される内容	復旧方法
起動時に環境変数がない	不足している変数（MCP_SVM_PAYMENT_ADDRESS、WATSONX_API_KEY、または WATSONX_PROJECT_ID／WATSONX_SPACE_ID）を示す1行の configuration error: … を出力して、プロセスが終了します。	変数を設定して再起動します。
有料ツールへの未払い呼び出し	USDC の価格と支払い先アドレスを示す x402 PaymentRequired エンベロープが返されます。これはエラーではなく、支払いループのステップ1です。	支払い後に再試行します（x402 対応クライアントでは自動的に処理されます）。
無効または不足額の支払い	ファシリテーターによる検証が拒否され、新しい PaymentRequired エンベロープが返されます。推論は実行されず、資金も決済されません。	表示された accepts に対して再署名します。
IBM 側の障害	ツールの結果 { "ok": false, "error": "watsonx_error", "message": "…", "status": … } が返されます。IAM 認証の失敗（WATSONX_API_KEY が無効）、モデルエラー、または watsonx.ai のタイムアウト（WATSONX_TIMEOUT_MS、デフォルトは90秒）が原因です。	メッセージに 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 エージェント、オンチェーン ID、エージェント決済を提供します。
ウェブサイト · 変更履歴 · GitHub}