Watsonx.data Document Library Retrieval MCP Server

The Watsonx.data Document Library Retrieval MCP Server is a Model Context Protocol (MCP)-compliant service that seamlessly connects AI agents with document libraries in watsonx.data, enabling intelligent data retrieval and interaction.

Key Features

• Dynamic Discovery & Registration
  Automatically detects and registers document libraries as MCP tools.

• Natural Language Interface
  Query document libraries using conversational language and receive human-readable responses.

• Minimal Configuration
  Deploy with simple setup requirements and zero complex configurations.

• Framework-Agnostic Integration
  Plug directly into the preferred agentic frameworks with native MCP compatibility.

---

Overview

• Protocol: Model Context Protocol (MCP)
• Purpose: Acts as a bridge between agentic AI frameworks and watsonx.data document libraries
• Supported Environments: IBM Cloud Pak for Data (CPD), Watsonx SaaS
• Agent Compatibility: The agentic framework must support the MCP standard (via SSE or Stdio).
  Note: This server will not function with agents that do not support MCP.

---

Prerequisites

• Python version 3.11 or later
• Access to your CPD or SaaS environment
• Access credentials and a CA certificate bundle for CPD
• Ensure your agent framework supports MCP protocol

---

Getting CA Bundle for CPD

1. Login to your OpenShift cluster:

   oc login -u kubeadmin -p '<your_openshift_password>' https://<your_openshift_cpd_url>:6443
   

2. Extract the root CA bundle:

   oc get configmap kube-root-ca.crt -o jsonpath='{.data.ca\.crt}' > cabundle.crt
   

NOTE: Please use open shift login command. The user and password will be open shift portal login username and password

---

Setup

Step 1: Install Python

• Official Installer: https://www.python.org/downloads/

Step 2: Create a virtual environment

python -m venv .venv

Step 3: Activate the virtual environment

source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

Step 4: Install the uv package manager

pip install uv

• uv package: https://pypi.org/project/uv/

Step 5: Install the MCP server package

pip install ibm-watsonxdata-dl-retrieval-mcp-server

---

Configuration

For Cloud Pak for Data (CPD):

export CPD_ENDPOINT="<cpd-endpoint>"
export CPD_USERNAME="<cpd-username>"
export CPD_PASSWORD="<cpd-password>"
export CA_BUNDLE_PATH="<absolute_path_to_cabundle.crt>"
export LH_CONTEXT="CPD"

NOTE:

• For CPD_ENDPOINT use endpoint url for installed CPD. Example: "https://cpd-cpd-instance.apps.perf10.5y2z.openshiftapps.com"
• For CPD_USERNAME and CPD_PASSWORD use the username and password used to login to CPD.

For Watsonx SaaS:

export WATSONX_DATA_API_KEY="<api-key>"
export WATSONX_DATA_RETRIEVAL_ENDPOINT="<retrieval-service-endpoint>"
export DOCUMENT_LIBRARY_API_ENDPOINT="<document-library-endpoint>"
export WATSONX_DATA_TOKEN_GENERATION_ENDPOINT="<token-generation-endpoint>"
export LH_CONTEXT="SAAS"

NOTE:

• For DOCUMENT_LIBRARY_API_ENDPOINT please use the endpoint url corresponding to region from here: https://cloud.ibm.com/apidocs/data-ai-common-core#endpoint-url. Example: https://api.ca-tor.dai.cloud.ibm.com
• For WATSONX_DATA_RETRIEVAL_ENDPOINT please use the watsonx.data endpoint. Example : https://console-ibm-cator.lakehouse.saas.ibm.com
• For WATSONX_DATA_TOKEN_GENERATION_ENDPOINT please use the endpoint url from here: https://cloud.ibm.com/apidocs/iam-identity-token-api#endpoints . Example: https://iam.cloud.ibm.com

---

Running the Server

uv run ibm-watsonxdata-dl-retrieval-mcp-server

By default, the server runs in sse transport mode on port 8000.

Transport: SSE

uv run ibm-watsonxdata-dl-retrieval-mcp-server --port <desired_port> --transport sse

Transport: stdio

uv run ibm-watsonxdata-dl-retrieval-mcp-server --port <desired_port> --transport stdio

---

Integrating with WXO

Prerequisite:

Install WXO ADK and complete the initial setup. Refer documentation for more details: https://developer.watson-orchestrate.ibm.com

Transport: STDIO

To add the MCP server in stdio transport with WXO refer the example below.

1. create connection

orchestrate connections add -a <app id>

2. Configure connection

orchestrate connections configure --app-id <app id> --environment draft -t team -k key_value

3. Setting credentials

orchestrate connections set-credentials --app-id=<app id> --env draft -e WATSONX_DATA_API_KEY="<api_key>" -e WATSONX_DATA_RETRIEVAL_ENDPOINT="<wxd retrieval endpoint>" -e DOCUMENT_LIBRARY_API_ENDPOINT="<DL endpoint>" -e WATSONX_DATA_TOKEN_GENERATION_ENDPOINT="<token generation endpoint>" -e LH_CONTEXT="SAAS"

Example for Saas:

orchestrate toolkits import \
    --kind mcp \
    --name "mcp-toolkit" \
    --description "mcp server for watsonx retrival service" \
    --package "ibm-watsonxdata-dl-retrieval-mcp-server" \
    --command "uv run ibm-watsonxdata-dl-retrieval-mcp-server --port <port> --transport stdio" \
    --language python \
    --tools "*" \
    --app-id <app id>

Transport: SSE

1. Install mcp-proxy

pip install mcp-proxy  

2. Run ibm-watsonxdata-dl-retrieval-mcp-server in sse transport.

Once prerequisites are met, the tools can be added as toolkit in WXO.

Example :

orchestrate toolkits import \ 
  --kind mcp \ 
  --name mcp_toolkit \ 
  --description "MCP server (hosted, SSE)" \ 
  --package "mcp-proxy" \ 
  --language python \ 
  --command "uvx mcp-proxy https://<mcp server endpoint>/sse" \ 
  --tools "*" 

NOTE:
When running wxo in SAAS and MCP server locally, expose the mcp server endpoint if required.

Refer wxo documentation for more details: https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=tools-importing-from-mcp-server

---

Integrating with other Agentic Frameworks

For more examples on using Watsonx.data Document Library Retrieval MCP Server with agentic framework refer examples

Limitations

• Environment credentials cannot be changed during runtime.
  • To change credentials, either:
    • Start a new server with new env variables, OR
    • Source new environment variables and restart the server.

Tool Naming

Each document library is registered with a unique tool name:

tool_name = <library_name><library_id>

Example:

invoice_document_library77e4b4dd_479e_4406_acc4_ce154c96266c

Release Notes

release 0.2.9

- Added fix for handling invalid characters in mcp tool name

release 0.2.8

- Implemented overrides for the list_tools and call_tools methods in the updated FastMcp framework.