@three-ws/ibm-x402-mcp
Summary: This server exposes IBM Granite foundation models as pay-per-use MCP tools that callers pay for in USDC on Solana via x402 — no IBM Cloud account needed — plus one free orientation tool.
ibm_granite_getting_started(free): Returns overview, per-tool pricing, x402 payment flow, setup requirements, and example calls; no payment or IBM credentials touched.ibm_granite_chat($0.02 USDC): Conversational completions with IBM Granite (defaultibm/granite-3-8b-instruct); accepts 1–50 role/content messages,temperature(0–2), andmax_new_tokens(1–4096).ibm_granite_code($0.025 USDC): Code generation, review, refactoring, explanation, unit-test writing, or documentation for a given task and code/prompt, with optional language and context.ibm_granite_embed($0.005 USDC): Batch embedding vectors for 1–64 texts (≤8,000 chars each) for semantic search, RAG retrieval, and clustering.ibm_granite_analyze($0.04 USDC): Structured JSON document analysis — entities, sentiment, risk signals, summary, and next steps — specialized for contract, financial, technical, medical, or sentiment focus.ibm_granite_forecast($0.05 USDC): Zero-shot time-series forecasting via IBM Granite TTM from 64–1024 ISO-8601 timestamped numeric points with a pandas cadence and 1–96 step horizon; no training required.
All tools are read-only inference calls (readOnlyHint: true, taskSupport: forbidden) — nothing on the caller's machine or accounts is modified — and x402-capable clients handle the 402 → sign → settle → retry loop automatically.
Enables pay-per-use AI model calls with USDC micropayments settled on the Solana blockchain.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@three-ws/ibm-x402-mcp write a Python script to download a web page"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that exposes IBM Granite foundation models as pay-per-use tools via the x402 payment protocol. End users pay USDC on Solana per call — no IBM Cloud account of their own. The server operator supplies IBM credentials (
WATSONX_*) and a receiving Solana wallet (MCP_SVM_PAYMENT_ADDRESS); callers supply only USDC. One free tool (ibm_granite_getting_started) explains prices and the flow before any payment.
Built by three.ws. Community-built and not affiliated with IBM.
How it works
An MCP client (Claude Desktop, Claude Code, Cursor, or an agent) connects to this server.
The client calls a tool — e.g.
ibm_granite_chat.Without an x402 payment payload, the server returns a
402 PaymentRequiredenvelope quoting the USDC price and the Solana receiving address.The client signs a Solana USDC transfer and retries with the payment in
_meta["x402/payment"].The server verifies and settles the payment via the facilitator, calls IBM watsonx.ai, and returns the result with a settlement receipt in
_meta["x402/payment-response"].
x402-capable MCP clients handle this loop automatically.
Related MCP server: omnicall-mcp
Install
npm install @three-ws/ibm-x402-mcpRun it directly with npx (no install needed):
MCP_SVM_PAYMENT_ADDRESS=<your-solana-wallet> \
WATSONX_API_KEY=<ibm-api-key> \
WATSONX_PROJECT_ID=<watsonx-project-id> \
npx @three-ws/ibm-x402-mcpOr install globally for the ibm-x402-mcp binary on your PATH:
npm install -g @three-ws/ibm-x402-mcpQuick start
Whoever runs the process is the operator: the server fails fast at startup without a payment address and IBM credentials (WATSONX_API_KEY, WATSONX_PROJECT_ID). Callers of the running server need only USDC — no IBM account. With Claude Code, one command:
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-mcpOr wire the server into your MCP client config (claude_desktop_config.json, Cursor's 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"
}
}
}
}Inspect the tool surface with the MCP Inspector:
npx -y @modelcontextprotocol/inspector npx @three-ws/ibm-x402-mcpTools
Tool | What it does | Price |
| Overview, prices, and the x402 payment flow. No payment or IBM account required. | Free |
| Conversational AI via IBM Granite (default | $0.02 USDC |
| Code generate, review, refactor, explain, test, document. | $0.025 USDC |
| Batch text embeddings for RAG, search, and clustering (1–64 texts). | $0.005 USDC |
| Structured document analysis: entities, sentiment, risk flags, summary, next steps. | $0.04 USDC |
| Zero-shot time-series forecasting via IBM Granite TTM (Tiny Time Mixer). | $0.05 USDC |
Every tool is a read-only model-inference call — nothing on your machine or in any account is modified — and declares MCP tool annotations (readOnlyHint, openWorldHint, idempotentHint) so clients can reason about side effects before paying.
Input parameters
ibm_granite_getting_started — section (optional: overview (default, everything) / pricing / payment / tools / setup).
ibm_granite_chat — messages (required: 1–50 { role, content } pairs; roles system/user/assistant, content ≤ 32,000 chars), model (default ibm/granite-3-8b-instruct), max_new_tokens (1–4096, default 1024), temperature (0–2, default 0.7).
ibm_granite_code — task (required: generate/review/refactor/explain/test/document), prompt (required, ≤ 16,000 chars: the description for generate, the code for everything else), language, context (≤ 4,000 chars).
ibm_granite_embed — inputs (required: 1–64 texts, ≤8000 chars each), model.
ibm_granite_analyze — document (required), analysis_type (general/contract/financial/technical/medical/sentiment, default general), language.
ibm_granite_forecast — timestamps (required: 64–1024 ISO-8601, uniform cadence, oldest first), values (required: 64–1024 numbers, same length), freq (required: pandas cadence, e.g. 1h, 1D), prediction_length (1–96), label.
Example calls
// 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" }Payment flow
This server uses the x402 protocol for micropayments:
Client calls a tool without payment →
402 PaymentRequiredwith the USDC amount and Solana address.Client builds and signs a Solana USDC transfer transaction.
Client retries with the signed tx in
_meta["x402/payment"].Server verifies and settles via the configured facilitator (default PayAI).
Server calls IBM watsonx.ai and returns the result with
_meta["x402/payment-response"](settlement receipt).
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 / TTMRequirements
Node.js >= 20.
A Solana wallet address to receive USDC (
MCP_SVM_PAYMENT_ADDRESS).IBM Cloud credentials: an API key (create one) and a watsonx.ai project id (Project → Manage → General → Project ID), or a deployment space id.
Environment variables
Variable | Required | Default |
| yes | — (aliases: |
| yes | — |
| yes (or | — |
| alternative to | — |
| no |
|
| no |
|
| no |
|
| no |
|
| no |
|
| no |
|
| no | three.ws fee payer |
| no |
|
| no | — (Bearer token for a private facilitator) |
| no | canonical Solana USDC mint |
Regional hosts: us-south, eu-de, eu-gb, jp-tok, au-syd, ca-tor — e.g. https://eu-de.ml.cloud.ibm.com.
Errors
Every failure state is explicit — there is no silent fallback:
State | What you see | Recovery |
Missing env at startup | The process exits with a one-line | Set the variable and restart. |
Unpaid call to a paid tool | An x402 | Pay and retry (x402-capable clients do this automatically). |
Invalid/underpaid payment | The facilitator rejects verification and a fresh | Re-sign against the quoted accepts. |
IBM-side failure | Tool result | The message carries IBM's reason; check credentials, project id, and region. |
Unexpected server fault | Tool result | Retry; file an issue if it persists. |
Facilitator unreachable at boot | A | Check |
ibm_granite_getting_started is always free and never touches IBM or the facilitator — use it to sanity-check the server before paying.
Related
@three-ws/ibm-watsonx-mcp— the same IBM Granite tools driven by your own IBM Cloud credentials (no x402, no per-call payment).
Links
Homepage: https://three.ws
Changelog: https://three.ws/changelog
License: Apache-2.0, see LICENSE
Support the project
If ibm-x402-mcp saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.
Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit
Built for AI agents too
Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/ibm-x402-mcp and it has the context it needs.
More from the same author
All repositories by nirholas: the full catalog, grouped by topic
three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
Questions or ideas: open an issue or start a discussion
Contributors
Star history
Part of three.ws
three.ws is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. @three-ws/ibm-x402-mcp is one package from it.
Documentation site: https://nirholas.github.io/ibm-x402-mcp/
Canonical source: https://github.com/nirholas/three.ws (this repository is a generated mirror of
packages/ibm-x402-mcp)Issues and ideas: https://github.com/nirholas/ibm-x402-mcp/issues
Available Tools
6 toolsibm_granite_analyzeIBM Granite Analyze ($0.04)ARead-only
Structured document analysis powered by IBM Granite: extract entities, sentiment, risk signals, a concise summary, and recommended next steps from any text (contracts, reports, emails, code reviews, etc.). Returns a machine-readable JSON analysis. Use this when you need machine-readable fields (entities, sentiment, risks) from a document rather than the free-text reply ibm_granite_chat gives. No IBM Cloud account required — pay $0.04 USDC per call via x402.
Inputs: document (required), language, analysis_type.
ibm_granite_chatIBM Granite Chat ($0.02)ARead-only
Chat completion powered by IBM Granite foundation models (default: ibm/granite-3-8b-instruct). Send a conversation as role/content message pairs and receive the assistant reply with token usage. Use this for open-ended conversation or free-form text generation; for code tasks call ibm_granite_code, and for structured JSON extraction call ibm_granite_analyze. No IBM Cloud account required — pay $0.02 USDC per call via x402.
Inputs: messages (required), model, temperature, max_new_tokens.
ibm_granite_codeIBM Granite Code ($0.025)ARead-only
Code generation, review, refactoring, and explanation via IBM Granite instruct models. Provide a task type and code/prompt; receive the generated or reviewed code with explanation. Use this when the input is source code or a request to write code; for general conversation call ibm_granite_chat instead. No IBM Cloud account required — pay $0.025 USDC per call via x402.
Inputs: task (required), prompt (required), context, language.
ibm_granite_embedIBM Granite Embed ($0.005)ARead-onlyIdempotent
Generate embedding vectors for one or more texts using IBM Granite (default: ibm/granite-embedding-278m-multilingual). Returns one float array per input, suitable for semantic search, RAG retrieval, and similarity scoring. Use this to index documents or compare texts by meaning; it returns vectors, not prose, so call ibm_granite_chat when you need a written answer. Up to 64 texts per call. No IBM Cloud account required — pay $0.005 USDC per call via x402.
Inputs: inputs (required), model.
ibm_granite_forecastIBM Granite Forecast ($0.05)ARead-only
Zero-shot time-series forecasting via IBM Granite TTM (Tiny Time Mixer). Provide a numeric series with ISO-8601 timestamps and a cadence, receive the forecast horizon. No training required. Suitable for revenue, traffic, sensor, energy, and financial series. Use this to project a numeric series of at least 64 timestamped points forward; it returns numbers only, so pass the result to ibm_granite_analyze if you need commentary. No IBM Cloud account required — pay $0.05 USDC per call via x402.
Inputs: freq (required), values (required), timestamps (required), label, +1 more.
ibm_granite_getting_startedGetting Started (free)ARead-onlyIdempotent
FREE — start here. Returns an overview of this server: the IBM Granite tools available, their per-call USDC prices, how the x402 pay-per-call flow works, setup requirements, and runnable example calls. No payment required. Call this first to orient before invoking a paid tool.
Inputs: section.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct Granite capability: chat for free-form text, analyze for structured JSON extraction, code for source-code tasks, forecast for time-series, embed for vectors, and getting_started for orientation. The descriptions explicitly cross-reference siblings (e.g., 'for code tasks call ibm_granite_code') to steer away from misselection.
All six tools share a predictable ibm_granite_ prefix with a short descriptive suffix. Minor deviation: getting_started is a phrase while the others are single nouns/verbs, but the overall pattern remains clear and readable.
Six tools is well-scoped for a pay-per-call Granite model gateway: one tool per model modality plus a free onboarding tool. Nothing is redundant and each tool has a clear, distinct role.
Covers the main Granite modalities — chat, code, embeddings, forecasting, and structured document analysis — plus free setup guidance. Minor gaps: no explicit model-list/selection tool and no batch chat beyond embed's 64-text limit, but agents can orient via getting_started.
Maintenance
Related MCP Connectors
Pay-per-use IBM Granite AI via x402: chat, code, embeddings, forecasting. USDC on Base or Solana.
Pay-per-call MCP tools over x402 (USDC/Solana): LLM, utilities, x402 market and model prices.
BridgeNode — x402 pay-per-request AI inference. OpenAI-compatible API + MCP, Solana USDC, gas-free.
Pay-per-call DeFi and macro intel for AI agents. x402 USDC tools via streamable HTTP /api/mcp.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for document intelligence via x402 micropayments. 6 tools: document analysis, invoice extraction, screenshot data, alt text, PII detection, sentiment analysis. Pay-per-use with USDC on Base — no API keys needed.61 npmMIT
- FlicenseNot gradedqualityCmaintenanceKeyless, pay-per-call AI gateway: 248 LLMs plus image/video/voice/music generation and live crypto, DeFi, markets, web-search and research tools through one MCP server. Pay per call in USDC via x402 on Base/Solana — no API key, no signup, free tier.-
- AlicenseAqualityCmaintenanceConnects Claude Desktop, Cursor, or any MCP-compatible client to 36+ frontier LLMs with automatic per-token payments in USDC on Solana.5MIT

GlianaAI MCP Serverofficial
AlicenseAqualityBmaintenanceEnables pay-per-call access to 90+ generative AI models and utility tools via any MCP client, with no signup or API key, using wallet-based USDC payments on Base, Tempo, or Solana.7317 npmMIT