Access watsonx Orchestrate functionality over an MCP server

The Model Context Protocol (MCP) is getting more accepted and integrated into various AI applications. watsonx Orchestrate ADK (Agent Development Kit) supports utilizing Watsonx Orchestrate functionality over an MCP server.

Extract from release notes of the watsonx Orchestrate ADK documentation:

watsonx Orchestrate MCP Server 
Access the watsonx Orchestrate documentation and all commands available via the ADK CLI through MCP. Empower your coding IDE of choice (including Bob) with the knowledge it needs to write watsonx Orchestrate Agents, Connections, and Tools. Then, conversationally interact with your watsonx Orchestrate instance to list, import or even export agents and tools from your IDE.

1. Why I Wanted to Try This

Since version 1.13.0, the watsonx Orchestrate ADK (Agent Development Kit) supports utilizing watsonx Orchestrate over an MCP server. I wanted to see live which tools are out-of-the-box provided in the new MCP server.

The result: a small but complete end-to-end setup to get the tools list from the watsonx Orchestrate Development Edition for local development.

The image below shows a simplified architecture diagram of the dependencies:

2. Running the example

Step 1: Set up the virtual Python environment

Start a new terminal in folder watsonx-orchestrate-mcp-adk and insert the following commands.

  1. Create a folder called watsonx-orchestrate-mcp-adk.
  2. Create a new virtual Python environment
  3. Load the virtual environment
md watsonx-orchestrate-mcp-adk
cd /watsonx-orchestrate-mcp-adk
python3.12 -m venv .venv
source ./.venv/bin/activate
python3 -m pip install --upgrade pip

Step 2: Install the watsonx Orchestrate Development Edition and the watsonx Orchestrate MCP server libraries

python3 -m pip install ibm-watsonx-orchestrate --upgrade
orchestrate --version
python3 -m pip install ibm-watsonx-orchestrate-mcp-server

Step 3: Generate the environment file for the ADK

This step is essential because the MCP server and the watsonx Orchestrate Developer Edition need different environment settings — and putting them together in one .env file simplifies experimentation.

touch .env

Here we ensure we have both settings for watsonx Orchestrate MCP server and watsonx Orchestrate Development Edition in the environment file.

  • watsonx Orchestrate Development Edition

Configuration for local usage and watsonx.ai.

To get the relevant information for the local configuration with IBM Cloud and watsonx.ai, please visit the blog post Getting Started with Local AI Agents in the watsonx Orchestrate Development Edition or the IBM watsonx Orchestrate ADK documentation.

  • watsonx Orchestrate MCP server

For details vist the watsonx Orchestrate MCP Server Documentation in the IBM watsonx Orchestrate ADK documentation.

The code below shows the content the environment file should contain.

######################################################################
############### watsonx Orchestrate Development Edition settings #####
# Developer
export WO_DEVELOPER_EDITION_SOURCE=myibm
# IBM ENTITLEMENT
export WO_ENTITLEMENT_KEY=<YOUR_ENTITLEMENT_KEY>
# IBM API KEY
export WATSONX_APIKEY=<YOUR_WATSONX_API_KEY>
export WATSONX_SPACE_ID=<YOUR_SPACE_ID>
# Optional configuration
#export WATSONX_REGION=us-south
#export WATSONX_URL=https://${WATSONX_REGION}.ml.cloud.ibm.com

######################################################################
############### watsonx Orchestrate MCP server settings ##############
# watsonx Orchestrate MCP server settings
export WXO_MCP_HOST=127.0.0.1
export WXO_MCP_PORT=8080
export WXO_MCP_TRANSPORT=http
export WXO_MCP_WORKING_DIRECTORY=$(pwd)

Step 4: Start the watsonx Orchestrate Developer Edition

You may need to reset the server configuration.

orchestrate server reset

Start the server with the local environment configuration, Langfuse for agent observation.

orchestrate env activate local
orchestrate server start --env-file .env --with-langfuse
orchestrate --version

Step 5: Start Lite Chat

orchestrate chat start

Step 6: Load the environment variable configuration before before we start the watsonx Orchestrate MCP server

source ./.env
echo "Configuration:"
echo "HOST:${WXO_MCP_HOST}\nPORT:\n${WXO_MCP_PORT}\nTRANPORT:${WXO_MCP_TRANSPORT}\nDIRECTORY:${WXO_MCP_WORKING_DIRECTORY}"

Step 7: Starting the watsonx Orchestrate MCP server

This is where the fun part starts ;-).

ibm-watsonx-orchestrate-mcp-server

Output:

 ╭──────────────────────────────────────────────────────────────────────────────╮               
 │                                                                              │               
 │                         ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█                        │               
 │                         █▀  █▀█ ▄▄█  █  █ ▀ █ █▄▄ █▀▀                        │               
 │                                                                              │               
 │                               FastMCP 2.13.0.2                               │               
 │                                                                              │               
 │                                                                              │               
 │              🖥  Server name: ibm-watsonx-orchestrate-mcp-server              │               
 │                                                                              │               
 │              📦 Transport:   HTTP                                            │               
 │              🔗 Server URL:  http://127.0.0.1:8080/mcp                       │               
 │                                                                              │               
 │              📚 Docs:        https://gofastmcp.com                           │               
 │              🚀 Hosting:     https://fastmcp.cloud                           │               
 │                                                                              │               
 ╰──────────────────────────────────────────────────────────────────────────────╯               


[11/12/25 19:25:19] [[INFO]] Starting MCP server                          server.py:2050
                                                   'ibm-watsonx-orchestrate-mcp-server' with                  
 transport 'http' on                                        
 http://127.0.0.1:8080/mcp                                  
[[INFO]]: Started server process [47933]
[[INFO]]: Waiting for application startup.
[[INFO]]: Application startup complete.
[[INFO]]: Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

Step 8: Connect to the MCP server with MCP inspector

Open a new terminal.

8.1 Install and start the MCP Inspector

export DANGEROUSLY_OMIT_AUTH=true   
npx @modelcontextprotocol/inspector

Step 8.2: Open the MCP inspector in the browser

open http://localhost:6274

Step 8.3: Use the MCP inspector

  • Connect
    • Transport Type: stdio
    • Url: http://127.0.0.1:8080/mcp

The output below shows the invocation of “List Agents” and we can see a single default agent is listed.

3. Summary

Working with watsonx Orchestrate MCP server together with watsonx Orchestrate Development Edition felt smooth and easy to set up. With the new watsonX Orchestrate MCP server, we can provide watsonX Orchestrate functionality in our own applications, enabling users to build their own agents or tools using interfaces other than the watsonX Orchestrate UIs, or to manage agents with the watsonx Orchestrate functionalities.

I hope this was useful to you and let’s see what’s next?

Greetings,

Thomas

#ai, #agents, #MCP, #watsonxOrchestrate, #AIIntegration, #AIAgents, #IBMDeveloper

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Blog at WordPress.com.

Up ↑