home / mcp / watsonx mcp server

watsonx MCP Server

MCP server enabling Claude Code to delegate tasks to IBM watsonx.ai foundation models for generation, chat, and embeddings.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "expertvagabond-watsonx-mcp-server": {
      "command": "node",
      "args": [
        "/Users/matthewkarsten/watsonx-mcp-server/index.js"
      ],
      "env": {
        "WATSONX_URL": "https://us-south.ml.cloud.ibm.com",
        "WATSONX_API_KEY": "YOUR_API_KEY",
        "WATSONX_SPACE_ID": "YOUR_DEPLOYMENT_SPACE_ID",
        "WATSONX_PROJECT_ID": "YOUR_PROJECT_ID"
      }
    }
  }
}

You deploy the watsonx MCP Server to let Claude Code delegate tasks to IBM watsonx.ai foundation models for text generation, chat interactions, and embeddings. It serves as a bridge that enables enterprise-grade models to handle specific workloads while Claude handles higher-level reasoning.

How to use

You connect your MCP client to the watsonx MCP Server to access text generation, chat, embeddings, and a model listing capability. The server communicates with watsonx.ai using your IBM Cloud credentials and configuration, enabling Claude to offload targeted tasks to Granite, Llama, Mistral, and related models. In practice, you configure the server, add it to your Claude setup, and then Claude can invoke the watsonx tools as part of your workflows.

How to install

Prerequisites you need before starting: a Node.js environment with npm installed.

Step 1: Install dependencies for the MCP server.

cd ~/watsonx-mcp-server
npm install

Configure your environment

Set the following environment variables to connect to watsonx.ai and to identify your deployment space or project.

WATSONX_API_KEY=your-ibm-cloud-api-key
WATSONX_URL=https://us-south.ml.cloud.ibm.com
WATSONX_SPACE_ID=your-deployment-space-id  # Recommended: deployment space
WATSONX_PROJECT_ID=your-project-id          # Alternative: project ID

Add to Claude Code

The MCP server configuration is shown here in the Claude integration example. This config tells Claude how to start and what environment variables to pass to the MCP server.

{
  "mcpServers": {
    "watsonx": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/matthewkarsten/watsonx-mcp-server/index.js"],
      "env": {
        "WATSONX_API_KEY": "your-api-key",
        "WATSONX_URL": "https://us-south.ml.cloud.ibm.com",
        "WATSONX_SPACE_ID": "your-deployment-space-id"
      }
    }
  }
}

Available tools

watsonx_generate

Generate text using watsonx.ai models.

watsonx_chat

Interact with watsonx.ai chat models.

watsonx_embeddings

Generate text embeddings for semantic search or RAG pipelines.

watsonx_list_models

List available watsonx.ai foundation models.