Watson Orchestrate

Official

by markusvankempen

Manage IBM Watson Orchestrate tools, agents, connections from Cursor, Copilot, Claude.

Manage IBM Watson Orchestrate tools, agents, and connections from multiple IDEs.

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:

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.
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.

code

┌─────────────────────────────────┐     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.

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.).

	Link
WxO Builder extension	VS Code Marketplace
Open VSX	open-vsx.org/extension/markusvankempen/wxo-builder
Author	markusvankempen.github.io
MCP Registry	registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server
Source Code	github.com/markusvankempen/wxo-builder-vscode-extension

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"):

code

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

Config JSON for Cursor deeplink generator:

json

{
  "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

bash

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

Set environment variables (or use .env):

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.

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

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:

json

{
    "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/:

File	Use for
`examples/.vscode/mcp.json`	VS Code / GitHub Copilot → copy to `.vscode/mcp.json`
`examples/.cursor/mcp.json`	Cursor → copy to `.cursor/mcp.json`
`examples/claude-desktop-config.json`	Claude Desktop → merge into `~/Library/Application Support/Claude/claude_desktop_config.json`
`examples/antigravity-mcp-config.json`	Antigravity → add to `mcp_config.json` via Manage MCP Servers
`examples/windsurf-mcp-config.json`	Windsurf → copy to `~/.codeium/windsurf/mcp_config.json`
`examples/env.example`	Optional `.env` for env vars

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)

list_skills – List all tools in the catalog (default limit 100)
list_tools_with_connections – List tools grouped by connection status (tools with connections vs standard tools). Matches the extension Tools view. Use for prompts like “list my Watson Orchestrate tools with active connections”.
list_standard_tools – List only standard tools (no connections). Returns accurate count and list.
get_skill – Get a tool by ID
delete_skill – Delete a tool
deploy_skill – Create a tool from OpenAPI spec. Set openapi_spec["x-ibm-connection-id"] to bind a connection to the tool
deploy_tool_from_url – Create a tool from a URL. Handles (1) APIs with API key → auto-creates connection, (2) public APIs (REST Countries, Open-Meteo) → no auth.
create_python_tool_from_tool_spec_json – Create a Python tool from tool-spec.json content. Pass the raw JSON string plus python_code and requirements. Use when user says "create a tool from this tool-spec.json" (e.g. CreatingZipFileBasedonDocuments).
create_python_tool_and_upload – Create a Python tool and upload its artifact in one step. tool_spec, python_code, optional requirements, python_filename.
create_tool_and_assign_to_agent – Create a tool from URL and assign to agent in one step. agent_id/agent_name optional if WO_AGENT_IDs is set.
assign_tool_to_agent – Assign a tool to an agent. agent_id/agent_name optional if WO_AGENT_IDs is set.
update_skill – Update name, description, permission (binding/connection not editable after creation)
copy_skill – Copy a tool. Use new_name (e.g. "MVKWeatherV2") to name the copy. Keeps connection and parameters. Names: letters, digits, underscores only.
execute_tool – Execute a tool by name or ID. agent_id optional; uses first from WO_AGENT_IDs when omitted.

Agents

list_agents – List all agents
get_agent – Get agent by ID or name. agent_id/agent_name optional if WO_AGENT_IDs is set.
get_agent_chat_starter_settings – Get welcome message and quick prompts. agent_id/agent_name optional if WO_AGENT_IDs is set.
update_agent_chat_starter_settings – Update welcome_message and quick_prompts. agent_id/agent_name optional if WO_AGENT_IDs is set.
list_agent_tools – List tools assigned to an agent with display names. agent_id/agent_name optional if WO_AGENT_IDs is set.
create_agent – Create an agent. Pass tools array to assign tools to the agent
update_agent – Update an agent. agent_id/agent_name optional if WO_AGENT_IDs is set.
update_agent_instructions_from_tools – Auto-generate and set instructions from assigned tools. agent_id/agent_name optional if WO_AGENT_IDs is set.
invoke_agent – Chat with an agent. agent_id/agent_name optional if WO_AGENT_IDs is set.
delete_agent – Delete an agent

Connections

list_connectors – List available connector catalog
list_connections – List configured connections (scope: draft, live, all)
list_active_live_connections – List only active and live connections (not tools), deduplicated. Use for "list all connections which are active and live, just the connections".
get_connection – Get connection by app_id
create_connection – Create a connection entry
delete_connection – Delete a connection
configure_connection – Set credentials (api_key, basic, bearer) for a connection

Flows

list_flows, get_flow, create_flow, delete_flow

Client Compatibility

The MCP server is tested and works with:

Client	Config	Notes
Cursor	`examples/.cursor/mcp.json`	stdio, npx or node
VS Code Copilot	`examples/.vscode/mcp.json`	Use `servers` key, `type: "stdio"`
Antigravity	`examples/antigravity-mcp-config.json`	Add via Manage MCP Servers
Langflow	STDIO or JSON mode	Output flattened for DataFrame; list tools have no limit/offset params

Langflow: Tool output is normalized to a list of flat dicts (primitive values only) so the MCP Tools component's DataFrame validation passes. Nested objects (e.g. binding, input_schema) are JSON-stringified. Cursor, VS Code, and Antigravity receive the same format and work identically.

Verification: Run npm run test:integration with WO_API_KEY and WO_INSTANCE_URL to validate core functionality. For Cursor/VS Code: add the server, ask "List my Watson Orchestrate tools" or "Which agents do I have?" For Langflow: add MCP server, connect MCP Tools to an Agent, run the flow.

Configuration

Set these environment variables (or use a .env file):

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

See Quick Start for full details on WO_AGENT_IDs and WO_AGENT_ID.

Troubleshooting

"Process exited with code 2" / "MCP server could not be started"

Ensure credentials are set – WO_API_KEY and WO_INSTANCE_URL must be in your MCP config env block or in a .env file.
Verify the server runs manually – From a terminal:
bash
```
WO_API_KEY=your-key WO_INSTANCE_URL=https://xxx.orchestrate.ibm.com npx -y wxo-builder-mcp-server
```
It should start and wait. Press Ctrl+C to exit.
Check Node version – Requires Node.js 18+.
WxO Builder extension – Ensure API Key and Instance URL are set in extension settings (search wxo-builder in VS Code settings).

Running Locally

bash

npm install
npm run build
node dist/index.js

Integration Tests

The test suite validates MCP parity with the extension using user-style test questions. See tests/README.md for full documentation. Test questions are defined in tests/test-questions.ts – add new ones to extend validation.

bash

# With WO credentials (runs all 4 tests)
WO_API_KEY=... WO_INSTANCE_URL=... npm run test:integration

# Without WO credentials (runs local execution test only)
npm run test:integration

Assigning Tools to Agents

Use create_agent or update_agent with a tools array of tool IDs:

json

{
    "name": "My Agent",
    "description": "...",
    "model_id": "groq/openai/gpt-oss-120b",
    "instructions": "...",
    "tools": ["tool-id-1", "tool-id-2"]
}

Assigning Connections to Tools

When deploying a tool with deploy_skill, include x-ibm-connection-id in the OpenAPI spec (or the connection’s app_id) to bind a connection:

json

{
  "tool_spec": { "name": "my_tool", "description": "..." },
  "openapi_spec": {
    "openapi": "3.0.1",
    "info": { "title": "My Tool", "version": "1.0.0" },
    "x-ibm-connection-id": "YOUR_APP_ID",
    "paths": { ... }
  }
}

Editor configuration (VS Code, Cursor, Claude Desktop, Antigravity, Windsurf)

Important: MCP config does not go in VS Code settings.json. Use the correct config file for your editor.

VS Code (with GitHub Copilot)

Config file: .vscode/mcp.json (workspace) or run MCP: Open User Configuration for global. Use npx (no .js path needed):

json

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

Cursor

Config file: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global). Uses mcpServers (not servers). Same command and args as above.

Antigravity (Google)

Open Manage MCP Servers → View raw config and add the watsonx entry from examples/antigravity-mcp-config.json to your mcp_config.json. Same mcpServers format as Cursor.

Windsurf (Codeium)

Config file: ~/.codeium/windsurf/mcp_config.json (macOS/Linux) or %USERPROFILE%\.codeium\windsurf\mcp_config.json (Windows). Use examples/windsurf-mcp-config.json. Same mcpServers format as Cursor. Restart Windsurf after changes.

Alternative: WxO Builder extension bundled server

If you installed the WxO Builder VSIX and want to use its bundled server (no npm install), use the extension path:

json

"command": "node",
"args": ["/Users/YOUR_USERNAME/.vscode/extensions/markusvankempen.wxo-builder-0.0.6/server/dist/index.js"]

Local build (devkit or standalone repo)

If you clone the devkit or the standalone repo, build and run via npx using the package directory (no .js path):

bash

cd packages/wxo-builder-mcp-server   # devkit
# or
cd wxo-builder-mcp-server            # standalone repo

npm install && npm run build

json

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

Publishing (for maintainers)

Publish to npm

From the devkit or standalone repo:

bash

cd packages/wxo-builder-mcp-server   # devkit
# or
cd .                                 # standalone repo root

npm run build
npm publish --access public

Publish to MCP Registry

Install the MCP publisher CLI: brew install mcp-publisher
Log in: mcp-publisher login github
Update server.json version to match package.json
Publish: mcp-publisher publish

The server will appear at registry.modelcontextprotocol.io as io.github.markusvankempen/wxo-builder-mcp-server.

Implementation: TypeScript vs Node.js

This MCP server is written in TypeScript and compiled to JavaScript. It loads an OpenAPI spec (watson-orchestrate-openapi.json) for documentation and discovery.

Why TypeScript for Watson Orchestrate:

Larger codebase (skills, agents, connections, flows, auth, models)
Type safety for Watson Orchestrate’s varied API responses
Easier to maintain and extend across multiple modules

License

Apache-2.0 — See LICENSE. CONTRIBUTING · CHANGELOG

Install

Configuration

Environment variables

WO_API_KEYrequiredsecret

IBM Cloud API key for Watson Orchestrate

WO_INSTANCE_URLrequired

Watson Orchestrate instance URL (e.g. https://xxx.orchestrate.ibm.com)

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "wxo-builder-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@markusvankempen/wxo-builder-mcp-server@1.0.4"
      ],
      "env": {
        "WO_API_KEY": "<YOUR_WO_API_KEY>",
        "WO_INSTANCE_URL": "<YOUR_WO_INSTANCE_URL>"
      }
    }
  }
}

WXO Builder MCP Server

Architecture & Data Flow

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

Directory listing copy (cursor.directory, etc.)

Install from npm

One-click install in Cursor

Quick Start

Example configs

Features (Parity with VS Code Extension)

OpenAPI Spec

Tools (Skills)

Agents

Connections

Flows

Client Compatibility

Configuration

Troubleshooting

Running Locally

Integration Tests

Assigning Tools to Agents

Assigning Connections to Tools

Editor configuration (VS Code, Cursor, Claude Desktop, Antigravity, Windsurf)

VS Code (with GitHub Copilot)

Cursor

Antigravity (Google)

Windsurf (Codeium)

Alternative: WxO Builder extension bundled server

Local build (devkit or standalone repo)

Publishing (for maintainers)

Publish to npm

Publish to MCP Registry

Implementation: TypeScript vs Node.js

License

Install

Configuration