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 as a Service environment.
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 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, use the following endpoint url corresponding to region https://cloud.ibm.com/apidocs/data-ai-common-core#endpoint-url (for example: https://api.ca-tor.dai.cloud.ibm.com).
- For WATSONX_DATA_RETRIEVAL_ENDPOINT, use the watsonx.data endpoint (for example: https://console-ibm-cator.lakehouse.saas.ibm.com).
- For WATSONX_DATA_TOKEN_GENERATION_ENDPOINT, use the following endpoint url https://cloud.ibm.com/apidocs/iam-identity-token-api#endpoints (for example: https://iam.cloud.ibm.com).

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