WXO Builder MCP Server

Version 1.0.4 · Author Markus van Kempen · Date 2026-02-20

MCP server for IBM Watson Orchestrate (WXO). Manage tools, agents, connections, flows, and execute tools from Cursor, VS Code Copilot, Claude Desktop, Antigravity, Windsurf, or the WxO Builder extension.

markusvankempen.github.io · WxO Builder extension · CONTRIBUTING · CHANGELOG · PUBLISHING · LICENSE

Architecture & Data Flow

This package has a dual role:

1. MCP protocol: It acts as an MCP server — your AI environment (Cursor, Claude Desktop, VS Code Copilot, Antigravity, Windsurf, etc.) is the MCP client that connects to it and calls tools.
2. Watson Orchestrate: It acts as an HTTP client — it makes REST requests to your Watson Orchestrate instance. Watson Orchestrate never connects back to this process.

┌─────────────────────────────────┐     MCP protocol      ┌──────────────────────────┐     HTTP (REST API)     ┌─────────────────────────┐
│  MCP Client                     │  ◄──────────────────► │  WXO Builder MCP Server │  ───────────────────►  │  Watson Orchestrate     │
│  (Cursor, Claude Desktop,       │     tool calls        │  (this package)          │     /v1/orchestrate/*  │  instance                │
│   Copilot, Antigravity, etc.)    │                       │                         │                        │  (your WO cloud/hosted)  │
└─────────────────────────────────┘                       └──────────────────────────┘                        └─────────────────────────┘

The MCP server exposes tools that proxy operations to Watson Orchestrate. When you invoke a tool (e.g. list_skills, invoke_agent), the server forwards the request to the Watson Orchestrate API and returns the result.

Related: WxO Builder Extension + MCP Server – a perfect combo

The WxO Builder extension and this MCP Server work together to create and administer Watson Orchestrate directly from your IDE. Use the extension for visual editing and the MCP server for AI-powered workflows (Cursor, Claude Desktop, etc.).

The extension provides visual tool creation, drag-and-drop agent editing, and local/remote testing. The MCP server exposes the same Watson Orchestrate capabilities to AI assistants in Cursor, Claude Desktop, Antigravity, Windsurf, and VS Code Copilot.

Directory listing copy (cursor.directory, etc.)

Cursor Deep Link (use this so the install dialog shows "WxO Builder MCP Server"):

cursor://anysphere.cursor-deeplink/mcp/install?name=WxO%20Builder%20MCP%20Server&config=eyJXeE8gQnVpbGRlciBNQ1AgU2VydmVyIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15IiwiQG1hcmt1c3ZhbmtlbXBlbi93eG8tYnVpbGRlci1tY3Atc2VydmVyIl0sImVudiI6eyJXT19BUElfS0VZIjoieW91ci1hcGkta2V5IiwiV09fSU5TVEFOQ0VfVVJMIjoiaHR0cHM6Ly95b3VyLWluc3RhbmNlLm9yY2hlc3RyYXRlLmlibS5jb20ifX19

Config JSON for Cursor deeplink generator:

{
  "WxO Builder MCP Server": {
    "command": "npx",
    "args": ["-y", "wxo-builder-mcp-server"],
    "env": {
      "WO_API_KEY": "your-api-key",
      "WO_INSTANCE_URL": "https://your-instance.orchestrate.ibm.com",
      "WO_AGENT_IDs": "agent-id-1,agent-id-2"
    }
  }
}

When WO_AGENT_IDs (comma-separated list) or WO_AGENT_ID is set, agent-based tools use the first ID as default when the user does not specify an agent.

Short description (≤100 chars):

Manage Watson Orchestrate tools, agents, connections. Pair with WxO Builder extension.

Longer description:

Manage IBM Watson Orchestrate (WXO) tools, agents, connections, and flows from Cursor, Copilot, or Claude. Best used with the WxO Builder VS Code extension for a full IDE experience: visual tool creation, drag-and-drop agents, and local/remote testing.

Distribution options:

• npm – Install wxo-builder-mcp-server (recommended)
• MCP Registry – registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server
• Standalone repo – github.com/markusvankempen/wxo-builder-mcp-server for cloning just the MCP server
• Devkit – This package is also part of the watsonx-orchestrate-devkit at packages/wxo-builder-mcp-server (shared with the WxO Builder extension)

Install from npm

npm install wxo-builder-mcp-server

One-click install in Cursor

Add to Cursor — Click to install (shows "WxO Builder MCP Server"). Then set WO_API_KEY and WO_INSTANCE_URL in Cursor MCP settings.

Quick Start

1. Set environment variables (or use .env):

WO_API_KEY=<your_ibm_cloud_api_key>
WO_INSTANCE_URL=https://<your-instance-id>.orchestrate.ibm.com

# Optional: default agent(s) when user omits agent_id/agent_name (first is used)
WO_AGENT_IDs=agent-id-1,agent-id-2
# Or single agent (backwards compatible):
# WO_AGENT_ID=<your-agent-id>

When WO_AGENT_IDs (comma-separated) or WO_AGENT_ID is set, tools use the first ID as default when the user does not specify an agent.

2. Configure your MCP client – use npx so you never reference .js paths. Example for Cursor (.cursor/mcp.json):

{
    "mcpServers": {
        "watsonx": {
            "command": "npx",
            "args": ["-y", "wxo-builder-mcp-server"],
            "env": {
                "WO_API_KEY": "your-api-key",
                "WO_INSTANCE_URL": "https://xxx.orchestrate.ibm.com"
            }
        }
    }
}

VS Code Copilot uses servers instead of mcpServers; same command and args:

{
    "servers": {
        "watsonx": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "wxo-builder-mcp-server"],
            "env": {
                "WO_API_KEY": "...",
                "WO_INSTANCE_URL": "https://...orchestrate.ibm.com"
            }
        }
    }
}

Example configs

Copy-ready example files are in examples/:

See examples/README.md for details.

Features (Parity with VS Code Extension)

OpenAPI Spec

• watson-orchestrate-openapi.json – OpenAPI 3.0 spec describing the Watson Orchestrate REST API used by this MCP server (tools, agents, connections, flows, runs). Use get_api_spec to retrieve it.
• get_api_spec – Returns the OpenAPI spec (full or summary). Use to discover what operations the Watson Orchestrate instance supports.

Tools (Skills)