Watson Orchestrate

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](cursor://anysphere.cursor-deeplink/mcp/install?name=WxO%20Builder%20MCP%20Server&config=eyJXeE8gQnVpbGRlciBNQ1AgU2VydmVyIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15IiwiQG1hcmt1c3ZhbmtlbXBlbi93eG8tYnVpbGRlci1tY3Atc2VydmVyIl0sImVudiI6eyJXT19BUElfS0VZIjoieW91ci1hcGkta2V5IiwiV09fSU5TVEFOQ0VfVVJMIjoiaHR0cHM6Ly95b3VyLWluc3RhbmNlLm9yY2hlc3RyYXRlLmlibS5jb20ifX19) — 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:// .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=

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.

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

• `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