Watson Orchestrate
Manage IBM Watson Orchestrate tools, agents, connections from Cursor, Copilot, Claude.
Open source Open in the app JSON README (API)
About
Manage IBM Watson Orchestrate tools, agents, connections from Cursor, Copilot, Claude.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- markusvankempen
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.4
- Last push
- 2026-02-23T20:07:27Z
- Repository state
- ativo
- License
- NOASSERTION
- Added
- 2026-08-29 04:00:29
- Updated
- 2026-08-29 04:00:29
- Origin id
io.github.markusvankempen/wxo-builder-mcp-server
README
# WXO Builder MCP Server
[](https://www.npmjs.com/package/wxo-builder-mcp-server)
[](https://www.npmjs.com/package/wxo-builder-mcp-server)
[](LICENSE)
<p align="center">
<img src="https://unpkg.com/wxo-builder-mcp-server/resources/icon.svg" alt="WXO Builder MCP Server" width="96" height="96"/>
</p>
<p align="center">
<a href="https://cursor.directory/mcp/wxo-builder-mcp-server"><img src="https://img.shields.io/badge/Add_to_Cursor-WXO%20Builder%20MCP-0f62fe?style=for-the-badge" alt="Add MCP server to Cursor" /></a>
</p>
**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](CONTRIBUTING.md) · [CHANGELOG](CHANGELOG.md) · [PUBLISHING](PUBLISHING.md) · [LICENSE](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](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=<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.
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/`](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`](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=<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](#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`](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](LICENSE). [CONTRIBUTING](CONTRIBUTING.md) · [CHANGELOG](CHANGELOG.md)