Watson Orchestrate
Manage IBM Watson Orchestrate tools, agents, connections from Cursor, Copilot, Claude.
Ask AI about Watson Orchestrate
Powered by Claude Β· Grounded in docs
I know everything about Watson Orchestrate. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.
βββββββββββββββββββββββββββββββββββ 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.).
| 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"):
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
- 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.
- Configure your MCP client β use
npxso you never reference.jspaths. 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/:
| 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). Useget_api_specto 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 IDdelete_skillβ Delete a tooldeploy_skillβ Create a tool from OpenAPI spec. Setopenapi_spec["x-ibm-connection-id"]to bind a connection to the tooldeploy_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 fromtool-spec.jsoncontent. Pass the raw JSON string pluspython_codeandrequirements. 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, optionalrequirements,python_filename.create_tool_and_assign_to_agentβ Create a tool from URL and assign to agent in one step.agent_id/agent_nameoptional ifWO_AGENT_IDsis set.assign_tool_to_agentβ Assign a tool to an agent.agent_id/agent_nameoptional ifWO_AGENT_IDsis set.update_skillβ Update name, description, permission (binding/connection not editable after creation)copy_skillβ Copy a tool. Usenew_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_idoptional; uses first fromWO_AGENT_IDswhen omitted.
Agents
list_agentsβ List all agentsget_agentβ Get agent by ID or name.agent_id/agent_nameoptional ifWO_AGENT_IDsis set.get_agent_chat_starter_settingsβ Get welcome message and quick prompts.agent_id/agent_nameoptional ifWO_AGENT_IDsis set.update_agent_chat_starter_settingsβ Updatewelcome_messageandquick_prompts.agent_id/agent_nameoptional ifWO_AGENT_IDsis set.list_agent_toolsβ List tools assigned to an agent with display names.agent_id/agent_nameoptional ifWO_AGENT_IDsis set.create_agentβ Create an agent. Passtoolsarray to assign tools to the agentupdate_agentβ Update an agent.agent_id/agent_nameoptional ifWO_AGENT_IDsis set.update_agent_instructions_from_toolsβ Auto-generate and set instructions from assigned tools.agent_id/agent_nameoptional ifWO_AGENT_IDsis set.invoke_agentβ Chat with an agent.agent_id/agent_nameoptional ifWO_AGENT_IDsis set.delete_agentβ Delete an agent
Connections
list_connectorsβ List available connector cataloglist_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_idcreate_connectionβ Create a connection entrydelete_connectionβ Delete a connectionconfigure_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):
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_KEYandWO_INSTANCE_URLmust be in your MCP configenvblock or in a.envfile. - Verify the server runs manually β From a terminal:
It should start and wait. Press Ctrl+C to exit.WO_API_KEY=your-key WO_INSTANCE_URL=https://xxx.orchestrate.ibm.com npx -y wxo-builder-mcp-server - Check Node version β Requires Node.js 18+.
- WxO Builder extension β Ensure API Key and Instance URL are set in extension settings (search
wxo-builderin VS Code settings).
Running Locally
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.
# 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
Test questions: List live connections | Copy tool | List standard tools | Create MVKWeather from URL | Execute locally/remotely | Agent chat | Exchange rate | REST Countries + assign | List agent tools | Create tool from tool-spec.json (CreatingZipFileBasedonDocuments) | Agent Conversation ZIP | Download tool artifact
Assigning Tools to Agents
Use create_agent or update_agent with a tools array of tool IDs:
{
"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:
{
"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):
{
"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:
"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):
cd packages/wxo-builder-mcp-server # devkit
# or
cd wxo-builder-mcp-server # standalone repo
npm install && npm run build
{
"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:
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.jsonversion to matchpackage.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
