WXO Builder

You can run and manage IBM Watson Orchestrate workflows from your IDE or editor through the WxO Builder MCP Server. This server exposes Watson Orchestrate capabilities to AI assistants and automation tools, enabling you to manage tools, agents, connections, and flows locally or remotely with a familiar development environment.

How to use

You use the MCP server by starting it as a local process (stdio) and configuring your MCP client to connect via the provided command. The server runs behind the scenes and exposes Watson Orchestrate capabilities to editors and assistants like Cursor, Claude Desktop, Antigravity, Windsurf, and the WxO Builder extension. Configure your client to point at the server by using the specified command, arguments, and environment variables.

How to install

Prerequisites: Node.js 18+ and npm. You will install the MCP server package from npm and then run or reference it from your MCP clients.

# Install the MCP server package
npm install @markusvankempen/wxo-builder-mcp-server

Configuration and usage notes

Set your IBM Watson Orchestrate credentials and instance URL as environment variables in your MCP client configuration. The typical required variables are WO_API_KEY and WO_INSTANCE_URL.

env WO_API_KEY=your-api-key
env WO_INSTANCE_URL=https://your-instance.orchestrate.ibm.com

Examples and practical configurations

Two common stdio configurations shown for Cursor and VS Code Copilot use npx to run the MCP server package with the necessary environment variables.

# Cursor / Copilot style configuration
{
  "mcpServers": {
    "watsonx": {
      "command": "npx",
      "args": ["-y", "@markusvankempen/wxo-builder-mcp-server"],
      "env": {
        "WO_API_KEY": "your-api-key",
        "WO_INSTANCE_URL": "https://your-instance.orchestrate.ibm.com"
      }
    }
  }
}

OpenAPI and capabilities you can access

The server provides endpoints to discover and work with Watson Orchestrate concepts such as tools, agents, connections, and flows. You can list, deploy, execute, and manage each of these resources through the MCP interface exposed by the server.

# Example: query the API spec endpoint (conceptual)
# get_api_spec → pay attention to the OpenAPI description

Troubleshooting and tips

If you encounter startup issues, ensure credentials are present, the server starts manually, and you are using a Node.js version that the server requires.

WO_API_KEY=your-key WO_INSTANCE_URL=https://xxx.orchestrate.ibm.com npx -y @markusvankempen/wxo-builder-mcp-server

Running locally

Install, build if needed, then run the server locally using the runtime command shown in examples.

npm install
npm run build
node dist/index.js

Available tools

list_skills

List all tools in the toolkit and their details.

list_tools_with_connections

List tools categorized by their connection status, showing tools with active connections and standard tools.

list_standard_tools

List only standard, non-connection tools.

get_skill

Retrieve a tool by its ID.

delete_skill

Remove a tool by its ID.

deploy_skill

Create a tool from an OpenAPI specification and bind it to a connection if provided.

deploy_tool_from_url

Create a tool from a URL, handling API keys or public APIs as applicable.

create_tool_and_assign_to_agent

Create a tool from a URL and assign it to a specific agent in one step.

assign_tool_to_agent

Link an existing tool to a specified agent.

update_skill

Update a tool’s name, description, and permissions.

copy_skill

Copy a tool, with a new name, preserving connections and parameters.

execute_tool

Run a tool by name or ID within a given agent context.

list_agents

List all agents.

get_agent

Retrieve an agent by ID.

get_agent_chat_starter_settings

Fetch welcome message and quick prompts for an agent.

update_agent_chat_starter_settings

Update welcome message and quick prompts for an agent.

list_agent_tools

List tools assigned to an agent.

create_agent

Create a new agent and optionally assign tools.

update_agent

Update an agent’s details, tools, and instructions.

update_agent_instructions_from_tools

Auto-generate agent instructions from assigned tools.

invoke_agent

Interact with an agent via chat using its ID or name.

delete_agent

Remove an agent.

list_connectors

List available connector catalog.

list_connections

List configured connections.

list_active_live_connections

List active live connections, deduplicated.

get_connection

Fetch a connection by app_id.

create_connection

Create a new connection entry.

delete_connection

Delete a connection.

configure_connection

Set credentials for a connection.

list_flows

List flows.

get_flow

Get a specific flow.

create_flow

Create a new flow.

delete_flow

Delete a flow.