\n\n**Version** 1.0.4 · **Author** [Markus van Kempen](mailto:markus.van.kempen@gmail.com) · **Date** 2026-02-20\n\nMCP 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.\n\n[markusvankempen.github.io](https://markusvankempen.github.io) · [WxO Builder extension](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder) · [CONTRIBUTING](CONTRIBUTING.md) · [CHANGELOG](CHANGELOG.md) · [PUBLISHING](PUBLISHING.md) · [LICENSE](LICENSE)\n\n## Architecture & Data Flow\n\nThis package has a **dual role**:\n\n1. **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.\n2. **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.\n\n```\n┌─────────────────────────────────┐ MCP protocol ┌──────────────────────────┐ HTTP (REST API) ┌─────────────────────────┐\n│ MCP Client │ ◄──────────────────► │ WXO Builder MCP Server │ ───────────────────► │ Watson Orchestrate │\n│ (Cursor, Claude Desktop, │ tool calls │ (this package) │ /v1/orchestrate/* │ instance │\n│ Copilot, Antigravity, etc.) │ │ │ │ (your WO cloud/hosted) │\n└─────────────────────────────────┘ └──────────────────────────┘ └─────────────────────────┘\n```\n\nThe 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.\n\n## Related: WxO Builder Extension + MCP Server – a perfect combo\n\nThe **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.).\n\n| | Link |\n|---|------|\n| **WxO Builder extension** | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder) |\n| **Open VSX** | [open-vsx.org/extension/markusvankempen/wxo-builder](https://open-vsx.org/extension/markusvankempen/wxo-builder) |\n| **Author** | [markusvankempen.github.io](https://markusvankempen.github.io) |\n| **MCP Registry** | [registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server](https://registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server) |\n| **Source Code** | [github.com/markusvankempen/wxo-builder-vscode-extension](https://github.com/markusvankempen/wxo-builder-vscode-extension) |\n\nThe 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.\n\n### Directory listing copy (cursor.directory, etc.)\n\n**Cursor Deep Link** (use this so the install dialog shows \"WxO Builder MCP Server\"):\n\n```\ncursor://anysphere.cursor-deeplink/mcp/install?name=WxO%20Builder%20MCP%20Server&config=eyJXeE8gQnVpbGRlciBNQ1AgU2VydmVyIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15IiwiQG1hcmt1c3ZhbmtlbXBlbi93eG8tYnVpbGRlci1tY3Atc2VydmVyIl0sImVudiI6eyJXT19BUElfS0VZIjoieW91ci1hcGkta2V5IiwiV09fSU5TVEFOQ0VfVVJMIjoiaHR0cHM6Ly95b3VyLWluc3RhbmNlLm9yY2hlc3RyYXRlLmlibS5jb20ifX19\n```\n\nConfig JSON for [Cursor deeplink generator](https://docs.cursor.com/deeplinks):\n\n```json\n{\n \"WxO Builder MCP Server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"wxo-builder-mcp-server\"],\n \"env\": {\n \"WO_API_KEY\": \"your-api-key\",\n \"WO_INSTANCE_URL\": \"https://your-instance.orchestrate.ibm.com\",\n \"WO_AGENT_IDs\": \"agent-id-1,agent-id-2\"\n }\n }\n}\n```\n\nWhen `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.\n\n**Short description (≤100 chars):**\n\n> Manage Watson Orchestrate tools, agents, connections. Pair with [WxO Builder extension](https://marketplace.visualstudio.com/items?itemName=MarkusvanKempen.wxo-builder).\n\n**Longer description:**\n\n> 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.\n\n---\n\n**Distribution options:**\n\n- **npm** – Install `wxo-builder-mcp-server` (recommended)\n- **MCP Registry** – [registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server](https://registry.modelcontextprotocol.io/?q=wxo-builder-mcp-server)\n- **Standalone repo** – [github.com/markusvankempen/wxo-builder-mcp-server](https://github.com/markusvankempen/wxo-builder-mcp-server) for cloning just the MCP server\n- **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)\n\n## Install from npm\n\n```bash\nnpm install wxo-builder-mcp-server\n```\n\n### One-click install in Cursor\n\n**[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.\n\n## Quick Start\n\n1. **Set environment variables** (or use `.env`):\n\n```env\nWO_API_KEY=\nWO_INSTANCE_URL=https://.orchestrate.ibm.com\n\n# Optional: default agent(s) when user omits agent_id/agent_name (first is used)\nWO_AGENT_IDs=agent-id-1,agent-id-2\n# Or single agent (backwards compatible):\n# WO_AGENT_ID=\n```\n\nWhen `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.\n\n2. **Configure your MCP client** – use `npx` so you never reference `.js` paths. Example for Cursor (`.cursor/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"watsonx\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"wxo-builder-mcp-server\"],\n \"env\": {\n \"WO_API_KEY\": \"your-api-key\",\n \"WO_INSTANCE_URL\": \"https://xxx.orchestrate.ibm.com\"\n }\n }\n }\n}\n```\n\nVS Code Copilot uses `servers` instead of `mcpServers`; same `command` and `args`:\n\n```json\n{\n \"servers\": {\n \"watsonx\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"wxo-builder-mcp-server\"],\n \"env\": {\n \"WO_API_KEY\": \"...\",\n \"WO_INSTANCE_URL\": \"https://...orchestrate.ibm.com\"\n }\n }\n }\n}\n```\n\n### Example configs\n\nCopy-ready example files are in [`examples/`](examples/):\n\n| File | Use for |\n|------|---------|\n| `examples/.vscode/mcp.json` | VS Code / GitHub Copilot → copy to `.vscode/mcp.json` |\n| `examples/.cursor/mcp.json` | Cursor → copy to `.cursor/mcp.json` |\n| `examples/claude-desktop-config.json` | Claude Desktop → merge into `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| `examples/antigravity-mcp-config.json` | Antigravity → add to `mcp_config.json` via Manage MCP Servers |\n| `examples/windsurf-mcp-config.json` | Windsurf → copy to `~/.codeium/windsurf/mcp_config.json` |\n| `examples/env.example` | Optional `.env` for env vars |\n\nSee [`examples/README.md`](examples/README.md) for details.\n\n## Features (Parity with VS Code Extension)\n\n### OpenAPI Spec\n\n- **`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.\n- **`get_api_spec`** – Returns the OpenAPI spec (full or summary). Use to discover what operations the Watson Orchestrate instance supports.\n\n### Tools (Skills)\n\n- **`list_skills`** – List all tools in the catalog (default limit 100)\n- **`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”.\n- **`list_standard_tools`** – List only standard tools (no connections). Returns accurate count and list.\n- **`get_skill`** – Get a tool by ID\n- **`delete_skill`** – Delete a tool\n- **`deploy_skill`** – Create a tool from OpenAPI spec. Set `openapi_spec[\"x-ibm-connection-id\"]` to **bind a connection** to the tool\n- **`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.\n- **`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)).\n- **`create_python_tool_and_upload`** – Create a Python tool and upload its artifact in one step. `tool_spec`, `python_code`, optional `requirements`, `python_filename`.\n- **`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.\n- **`assign_tool_to_agent`** – Assign a tool to an agent. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.\n- **`update_skill`** – Update name, description, permission (binding/connection not editable after creation)\n- **`copy_skill`** – Copy a tool. Use `new_name` (e.g. \"MVKWeatherV2\") to name the copy. Keeps connection and parameters. Names: letters, digits, underscores only.\n- **`execute_tool`** – Execute a tool by name or ID. `agent_id` optional; uses first from `WO_AGENT_IDs` when omitted.\n\n### Agents\n\n- **`list_agents`** – List all agents\n- **`get_agent`** – Get agent by ID or name. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.\n- **`get_agent_chat_starter_settings`** – Get welcome message and quick prompts. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.\n- **`update_agent_chat_starter_settings`** – Update `welcome_message` and `quick_prompts`. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.\n- **`list_agent_tools`** – List tools assigned to an agent with display names. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.\n- **`create_agent`** – Create an agent. Pass `tools` array to **assign tools** to the agent\n- **`update_agent`** – Update an agent. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.\n- **`update_agent_instructions_from_tools`** – Auto-generate and set instructions from assigned tools. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.\n- **`invoke_agent`** – Chat with an agent. `agent_id`/`agent_name` optional if `WO_AGENT_IDs` is set.\n- **`delete_agent`** – Delete an agent\n\n### Connections\n\n- **`list_connectors`** – List available connector catalog\n- **`list_connections`** – List configured connections (scope: draft, live, all)\n- **`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\".\n- **`get_connection`** – Get connection by app_id\n- **`create_connection`** – Create a connection entry\n- **`delete_connection`** – Delete a connection\n- **`configure_connection`** – Set credentials (api_key, basic, bearer) for a connection\n\n### Flows\n\n- **`list_flows`**, **`get_flow`**, **`create_flow`**, **`delete_flow`**\n\n## Client Compatibility\n\nThe MCP server is tested and works with:\n\n| Client | Config | Notes |\n|--------|--------|------|\n| **Cursor** | `examples/.cursor/mcp.json` | stdio, npx or node |\n| **VS Code Copilot** | `examples/.vscode/mcp.json` | Use `servers` key, `type: \"stdio\"` |\n| **Antigravity** | `examples/antigravity-mcp-config.json` | Add via Manage MCP Servers |\n| **Langflow** | STDIO or JSON mode | Output flattened for DataFrame; list tools have no limit/offset params |\n\n**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.\n\n**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.\n\n## Configuration\n\nSet these environment variables (or use a `.env` file):\n\n```env\nWO_API_KEY=\nWO_INSTANCE_URL=https://.orchestrate.ibm.com\n\n# Optional: default agent(s) when user omits agent_id/agent_name (first is used)\nWO_AGENT_IDs=agent-id-1,agent-id-2\n```\n\nSee [Quick Start](#quick-start) for full details on `WO_AGENT_IDs` and `WO_AGENT_ID`.\n\n## Troubleshooting\n\n**\"Process exited with code 2\" / \"MCP server could not be started\"**\n\n1. **Ensure credentials are set** – `WO_API_KEY` and `WO_INSTANCE_URL` must be in your MCP config `env` block or in a `.env` file.\n2. **Verify the server runs manually** – From a terminal:\n ```bash\n WO_API_KEY=your-key WO_INSTANCE_URL=https://xxx.orchestrate.ibm.com npx -y wxo-builder-mcp-server\n ```\n It should start and wait. Press Ctrl+C to exit.\n3. **Check Node version** – Requires Node.js 18+.\n4. **WxO Builder extension** – Ensure **API Key** and **Instance URL** are set in extension settings (search `wxo-builder` in VS Code settings).\n\n## Running Locally\n\n```bash\nnpm install\nnpm run build\nnode dist/index.js\n```\n\n## Integration Tests\n\nThe test suite validates MCP parity with the extension using **user-style test questions**. See [`tests/README.md`](tests/README.md) for full documentation. Test questions are defined in `tests/test-questions.ts` – add new ones to extend validation.\n\n```bash\n# With WO credentials (runs all 4 tests)\nWO_API_KEY=... WO_INSTANCE_URL=... npm run test:integration\n\n# Without WO credentials (runs local execution test only)\nnpm run test:integration\n```\n\n**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\n\n## Assigning Tools to Agents\n\nUse `create_agent` or `update_agent` with a `tools` array of tool IDs:\n\n```json\n{\n \"name\": \"My Agent\",\n \"description\": \"...\",\n \"model_id\": \"groq/openai/gpt-oss-120b\",\n \"instructions\": \"...\",\n \"tools\": [\"tool-id-1\", \"tool-id-2\"]\n}\n```\n\n## Assigning Connections to Tools\n\nWhen 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:\n\n```json\n{\n \"tool_spec\": { \"name\": \"my_tool\", \"description\": \"...\" },\n \"openapi_spec\": {\n \"openapi\": \"3.0.1\",\n \"info\": { \"title\": \"My Tool\", \"version\": \"1.0.0\" },\n \"x-ibm-connection-id\": \"YOUR_APP_ID\",\n \"paths\": { ... }\n }\n}\n```\n\n## Editor configuration (VS Code, Cursor, Claude Desktop, Antigravity, Windsurf)\n\n**Important:** MCP config does **not** go in VS Code `settings.json`. Use the correct config file for your editor.\n\n### VS Code (with GitHub Copilot)\n\nConfig file: **`.vscode/mcp.json`** (workspace) or run **MCP: Open User Configuration** for global. Use `npx` (no .js path needed):\n\n```json\n{\n \"servers\": {\n \"watsonx\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"wxo-builder-mcp-server\"],\n \"env\": {\n \"WO_API_KEY\": \"...\",\n \"WO_INSTANCE_URL\": \"https://...orchestrate.ibm.com\"\n }\n }\n }\n}\n```\n\n### Cursor\n\nConfig file: **`.cursor/mcp.json`** (project) or `~/.cursor/mcp.json` (global). Uses `mcpServers` (not `servers`). Same `command` and `args` as above.\n\n### Antigravity (Google)\n\nOpen **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.\n\n### Windsurf (Codeium)\n\nConfig 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.\n\n### Alternative: WxO Builder extension bundled server\n\nIf you installed the WxO Builder VSIX and want to use its bundled server (no npm install), use the extension path:\n\n```json\n\"command\": \"node\",\n\"args\": [\"/Users/YOUR_USERNAME/.vscode/extensions/markusvankempen.wxo-builder-0.0.6/server/dist/index.js\"]\n```\n\n### Local build (devkit or standalone repo)\n\nIf 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):\n\n```bash\ncd packages/wxo-builder-mcp-server # devkit\n# or\ncd wxo-builder-mcp-server # standalone repo\n\nnpm install && npm run build\n```\n\n```json\n{\n \"servers\": {\n \"watsonx\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"/path/to/wxo-builder-mcp-server\"],\n \"env\": {\n \"WO_API_KEY\": \"...\",\n \"WO_INSTANCE_URL\": \"https://...orchestrate.ibm.com\"\n }\n }\n }\n}\n```\n\n## Publishing (for maintainers)\n\n### Publish to npm\n\nFrom the devkit or standalone repo:\n\n```bash\ncd packages/wxo-builder-mcp-server # devkit\n# or\ncd . # standalone repo root\n\nnpm run build\nnpm publish --access public\n```\n\n### Publish to MCP Registry\n\n1. Install the MCP publisher CLI: `brew install mcp-publisher`\n2. Log in: `mcp-publisher login github`\n3. Update `server.json` version to match `package.json`\n4. Publish: `mcp-publisher publish`\n\nThe server will appear at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) as `io.github.markusvankempen/wxo-builder-mcp-server`.\n\n## Implementation: TypeScript vs Node.js\n\nThis MCP server is written in **TypeScript** and compiled to JavaScript. It loads an OpenAPI spec (`watson-orchestrate-openapi.json`) for documentation and discovery.\n\n**Why TypeScript for Watson Orchestrate:**\n\n- Larger codebase (skills, agents, connections, flows, auth, models)\n- Type safety for Watson Orchestrate’s varied API responses\n- Easier to maintain and extend across multiple modules\n\n## License\n\nApache-2.0 — See [LICENSE](LICENSE). [CONTRIBUTING](CONTRIBUTING.md) · [CHANGELOG](CHANGELOG.md)\n",
"bytes": 20309,
"sha": "8a6415457f533a4913dab085216f3e3f6196006a645360fa0740d76d4da66baf",
"repo_slug": "markusvankempen/wxo-builder-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_markusvankempen_wxo_builder_mc_eb5734ee/readme"
}
![\"WXO](\"https://unpkg.com/wxo-builder-mcp-server/resources/icon.svg\"){kind=icon}
\n![\"Add](\"https://img.shields.io/badge/Add_to_Cursor-WXO%20Builder%20MCP-0f62fe?style=for-the-badge\"){kind=icon}