README - ibm-watsonxdata-dl-retrieval-mcp-server by ibm

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

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

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/

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
Install mcp-proxy

pip install mcp-proxy

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

Once prerequisites are met, the tools can be added as toolkit in WXO. Refer documentation for more details: https://developer.watson-orchestrate.ibm.com/tools/toolkits

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.

Integrating with other Agentic Frameworks

For more examples on using Watsonx.data Document Library Retrieval MCP Server with agentic framework refer examples session here: https://github.com/IBM/ibm-watsonxdata-dl-retrieval-mcp-server

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