# Watson Orchestrate [Health: Active] **Category:** 💻 Developer Tools **Repository:** https://github.com/markusvankempen/wxo-builder-mcp-server **GitHub Stars:** 0 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/watson-orchestrate ## Description Manage IBM Watson Orchestrate tools, agents, connections from Cursor, Copilot, Claude. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "watson-orchestrate": { "command": "npx", "args": ["-y","or"] } } ``` ## Documentation & README # WXO Builder MCP Server [![npm version](https://img.shields.io/npm/v/wxo-builder-mcp-server.svg)](https://www.npmjs.com/package/wxo-builder-mcp-server) [![npm downloads](https://img.shields.io/npm/dm/wxo-builder-mcp-server.svg)](https://www.npmjs.com/package/wxo-builder-mcp-server) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

WXO Builder MCP Server

Add MCP server to Cursor

**Version** 1.0.4 · **Author** [Markus van Kempen](mailto:markus.van.kempen@gmail.com) · **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](https://markusvankempen.github.io) · [WxO Builder extension](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder) · [CONTRIBUTING](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/CONTRIBUTING.md) · [CHANGELOG](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/CHANGELOG.md) · [PUBLISHING](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/PUBLISHING.md) · [LICENSE](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/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.). | | Link | |---|------| | **WxO Builder extension** | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder) | | **Open VSX** | [open-vsx.org/extension/markusvankempen/wxo-builder](https://open-vsx.org/extension/markusvankempen/wxo-builder) | | **Author** | [markusvankempen.github.io](https://markusvankempen.github.io) | | **MCP Registry** | [registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server](https://registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server) | | **Source Code** | [github.com/markusvankempen/wxo-builder-vscode-extension](https://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](https://docs.cursor.com/deeplinks): ```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](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder). **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](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder) 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](https://registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server) - **Standalone repo** – [github.com/markusvankempen/wxo-builder-mcp-server](https://github.com/markusvankempen/wxo-builder-mcp-server) for cloning just the MCP server - **Devkit** – This package is also part of the [watsonx-orchestrate-devkit](https://github.com/markusvankempen/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](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/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`): ```env WO_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. 2. **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/`](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/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`](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/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](https://github.com/markusvankempen/watsonx-orchestrate-devkit/tree/main/packages/vscode-extension/tests/fixtures/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= 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 ``` See [Quick Start](#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"** 1. **Ensure credentials are set** – `WO_API_KEY` and `WO_INSTANCE_URL` must be in your MCP config `env` block or in a `.env` file. 2. **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. 3. **Check Node version** – Requires Node.js 18+. 4. **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`](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/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 ``` **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: ```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](https://github.com/markusvankempen/wxo-builder-mcp-server), 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 1. Install the MCP publisher CLI: `brew install mcp-publisher` 2. Log in: `mcp-publisher login github` 3. Update `server.json` version to match `package.json` 4. Publish: `mcp-publisher publish` The server will appear at [registry.modelcontextprotocol.io](https://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](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/LICENSE). [CONTRIBUTING](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/CONTRIBUTING.md) · [CHANGELOG](https://github.com/markusvankempen/wxo-builder-mcp-server/blob/HEAD/CHANGELOG.md)