IBM watsonx.data local Model Context Protocol (MCP) server

IBM watsonx.data local 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 of watsonx.data local MCP server:

Dynamic discovery and registration: Automatically detects and registers document libraries as MCP tools.
Natural language interface: Query document libraries using natural 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.

Note: To uniquely identify each document library, the MCP server adds a tool and the tool name combines the document library name and document library id. For example: invoice_document_library77e4b4dd_479e_4406_acc4_ce154c96266c.

Prerequisites

Before you using the local MCP server, make sure that the following prerequisites are met:

Python 3.11 or greater installed on your system. If Python is not already installed on your system, download and install Python from https://www.python.org/downloads/.
Access to your watsonx.data environment.
Access credentials and a CA certificate bundle for On-prem environment, complete the following steps to get CA bundle:
1. Run the following command to login to OpenShift cluster.
```
oc login -u kubeadmin -p '<your_openshift_password>' https://<your_openshift_cpd_url>:6443
```
2. Run the following command to extract the root CA bundle.
```
oc get configmap kube-root-ca.crt -o jsonpath='{.data.ca\.crt}' > cabundle.crt
```
Note: Use the open shift login command with your open shift portal username and password.
Make sure that your agent framework supports the MCP protocol.

Provisioning the MCP server

To provision the local MCP server, complete the following steps:

Run the following command to create a virtual environment.
```
   python -m venv .venv
```

Run the following commands to activate the virtual environment.

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

Run the following command to install the uv package manager.
```
pip install uv
```
Or, download and install the uv packages.
Run the following command to install the MCP server package.
```
pip install ibm-watsonxdata-dl-retrieval-mcp-server
```
Run the following commands to set the required environment variables for watsonx.data.
```
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 watsonx.data environment (For 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 watsonx.data environment.

Running the local MCP server

After the environment is set up and dependencies are installed, run the following command.

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

By default, the MCP server runs in sse transport mode on port 8000. To transport sse, run the following command.

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

To transport stdio, run the following command.

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

Integration options for MCP server

You can integrate a remote MCP server with watsonx Orchestrate and other agentic frameworks. For more details, see the following topics:

Limitation

You cannot change creditials set through environment variables during runtime. To use local MCP server with differenet credential, either start a new server instance with updated environment variables or source the new variables and restart the existing server instance.

Learn more

Parent topic: Retrieval service