wxo-builder-mcp-server

v1.0.13

Published

15 days ago

MCP server for IBM Watson Orchestrate (WXO): manage tools, agents, flows, Python tools from Cursor, VS Code, Claude. Deploy from URL, create from tool-spec.json.

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 · DOCUMENTATION · CONTRIBUTING · CHANGELOG · 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 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/:

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

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

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

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