MCP server for IBM Decision Intelligence and IBM Automation Decision Services

This Model Context Protocol (MCP) server empowers AI assistants by accessing decisions from IBM Decision Intelligence or IBM Automation Decision Services.

The MCP server is available as an npm package in the free npm registry at https://www.npmjs.com/package/di-mcp-server.

It supports both STDIO and streamable HTTP transports for local or remote deployments for supporting any MCP clients.

flowchart LR
    github["di-mcp-server github repository"] -- publish --> registry
    registry["NPM registry"] -- npx -y di-mcp-server--> server

    subgraph MCP Host 
        client["MCP Client"] <-- MCP/STDIO --> server("DI MCP Server")
    end

    server -- HTTPS --> runtime("Decision Runtime")

    subgraph id["Decision Intelligence<br>or Automation Decision Services"]
        runtime
    end


    client <-- MCP/HTTP --> server2("DI MCP Server") -- HTTPS --> runtime

Loading

Resources

• Supercharge your AI Assistants with the decisioning capabilities of IBM Decision Intelligence: step by step instructions to use this MCP server for IBM Decision Intelligence

Getting started with the MCP server

You can use the MCP server available in the npm registry. If you want to develop your own MCP server or contribute to the development, see Developing the MCP server.

You can run the MCP server with npx to expose each operation of the last deployed version of a decision service as a MCP tool:

npx -y di-mcp-server <CREDENTIALS> --url <RUNTIME_BASE_URL> [--transport <TRANSPORT>] [--runtime <RUNTIME>] [--deployment-spaces <DEPLOYMENT_SPACES>]

where

• CREDENTIALS is one of the following options:

  • --apikey <DI_API_KEY> where DI_API_KEY is the API key for accessing the decision runtime of IBM Decision Intelligence.
  • --username <USERNAME> --password <PASSWORD> where USERNAME and PASSWORD are the basic authentication credentials to connect to the decision runtime of IBM Automation Decision Services.
  • --username <USERNAME> --apikey <ZEN_API_KEY> where USERNAME and ZEN_API_KEY are the Zen API key credentials to access the decision runtime of IBM Automation Decision Services (see Authorizing HTTP requests by using the Zen API key)

• RUNTIME_BASE_URL is the base URL of the decision runtime REST API. For IBM Decision Intelligence its pattern is: https://<TENANT_NAME>.decision-prod-us-south.decision.saas.ibm.com/ads/runtime/api/v1 where TENANT_NAME is the name of the tenant.

• TRANSPORT (optional) is the transport protocol, either STDIO (default) or HTTP.

• RUNTIME (optional) is the decision runtime, either DI (default) or ADS for using the decision runtime of respectively IBM Decision Intelligence or IBM Automation Decision Services.

• DEPLOYMENT_SPACES (optional) is a comma-separated list of deployment spaces to scan (defaults to development).

• Example:

npx -y di-mcp-server --apikey HRJcDNlNXZVWlk9 --url https://mytenant.decision-prod-us-south.decision.saas.ibm.com/ads/runtime/api/v1

Integrating decision services into AI applications

The MCP server for Decision Intelligence extends its capability by enabling AI applications, such as IBM watsonx Orchestrate and Claude, to discover and execute deployed decision services.

Integrating decision services into IBM watsonx Orchestrate

You can integrate decision services into IBM watsonx Orchestrate by adding the MCP server.

1. In the agent builder, click Add tool.

   

2. Click Import

   

3. Then click Import from mcp server

   

4. Click Add MCP server

   

5. Specify the name for the server and the npx command that is explained in the Getting started section.

   

6. Close the dialog box, and select the tool that you want to add to your agent.

   

   Your agent is now empowered with decisions.

Use a connection to specify the APIKEY and URL environment variables

1. Open the main menu, then click Manage, then click Connections, to open the Connection settings

   

2. Click Add new connection to launch the Add new connection wizard

   

3. Fill in the Connection ID and Display name fields, then click Save and continue

   

4. In the Configure draft connection panel:

   • Select Key Value Pair as Authentication Type
   • Fill-in the Key and Value fields to define the APIKEY environment variable
   • Then click Add key value pair

   

5. Fill-in the Key and Value fields to define the URL environment variable, then click Connect

   

6. When the draft connection is connected, click Next

   

7. Similarly configure the live connection, then click Add connection

   

8. In the Add MCP Server wizard:

   • Select the display name corresponding to the connection you just configured
   • Fill-in the npx command WITHOUT the --apikey and --url arguments
   • Click Connect then Done

   

Integrating decision services into Claude Desktop

You can integrate decision services into Claude Desktop by adding the MCP server.

1. Locate the Claude Desktop configuration file.

   Find your Claude configuration directory:

   • macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ${HOME}/.config/Claude/claude_desktop_config.json

2. Add the MCP server configuration to the configuration file.

   • In the configuration directory, edit or create claude_desktop_config.json:

     {
         [..]
         "mcpServers": {
             "di-mcp-server": {
                 "command": "npx",
                 "args": [
                     "-y",
                     "di-mcp-server",
                     "--apikey",
                     "<APIKEY>",
                     "--url",
                     "https://<TENANT_NAME>.decision-prod-us-south.decision.saas.ibm.com/ads/runtime/api/v1"
                 ]
             }
         }
         [..]
     }

   • Alternatively, you can use the APIKEY and URL environment variables to respectively specify the API key and the base URL of the decision runtime REST API:

     {
         [..]
         "mcpServers": {
             "di-mcp-server": {
                 "command": "npx",
                 "args": ["-y", "di-mcp-server"],
                 "env": {
                     "APIKEY": "<APIKEY>",
                     "URL": "https://<TENANT_NAME>.decision-prod-us-south.decision.saas.ibm.com/ads/runtime/api/v1"
                 }
             }
         }
         [..]
     }

For more information, see https://modelcontextprotocol.io/quickstart/user.

Integrating decision services into Cursor

1. In Cursor, click the cog wheel icon to open Cursor settings

2. Click Tools & Integration in the setting categories listed on the left-hand side

   

3. Click + New MCP Server, this will open Cursor's mcp.json configuration file

   

4. Add a new MCP server entry. As for Claude Desktop, you can specify the API key and base URL of the decision runtime REST API using:

   • Either command line arguments:

     {
         [..]
         "mcpServers": {
             "di-mcp-server": {
                 "command": "npx",
                 "args": [
                     "-y",
                     "di-mcp-server",
                     "--apikey",
                     "<APIKEY>",
                     "--url",
                     "https://<TENANT_NAME>.decision-prod-us-south.decision.saas.ibm.com/ads/runtime/api/v1"
                 ]
             }
         }
         [..]
     }

   • Or environment variables:

     {
         [..]
         "mcpServers": {
             "di-mcp-server": {
                 "command": "npx",
                 "args": ["-y", "di-mcp-server"],
                 "env": {
                     "APIKEY": "<APIKEY>",
                     "URL": "https://<TENANT_NAME>.decision-prod-us-south.decision.saas.ibm.com/ads/runtime/api/v1"
                 }
             }
         }
         [..]
     }

For more information, see Cursor's documentation about Installing MCP servers.

Using Custom Tool Names

When integrating with MCP hosts, you may need to customize the tool names to meet specific requirements or limitations, such as:

• Maximum length restrictions
• Forbidden characters
• Naming conventions

Default Tool Naming Algorithm

By default, tool names are generated as follows:

1. Combines the decision service name with the operation ID: decisionServiceName operationID
2. Replaces spaces and forward slashes with underscores: decisionServiceName_operationID
3. Handles name collisions by using the decision service ID: use decisionServiceID_operationID if decisionServiceName_operationID already exists

Customizing Tool Names with the decision REST API

If the default naming strategy doesn't meet the requirements of your MCP hosts, you can specify custom tool names by setting the mcpToolName.OPERATION_ID decision metadata:

{
  "map": {
    [..]
    "mcpToolName.OPERATION_ID": {
      "name": "mcpToolName.OPERATION_ID",
      "kind": "PLAIN",
      "readOnly": false,
      "value": "YourCustomToolName"
    }
    [..]
  }
}

where

• OPERATION_ID is the operation unique identifier
• YourCustomToolName is the desired tool name for the operation

Developing the MCP server

You can develop your own MCP server by using the source files that are available here.

Getting source files

Run the following command to get the source files of the MCP server:

git clone https://github.com/DecisionsDev/di-mcp-server.git
cd di-mcp-server

Building the MCP server

Run the following commands to build the MCP server from the source files:

npm install
npm run build

Testing the MCP server

Run the following command to test the MCP server:

npm test

Code Coverage

The project is configured with Jest's built-in code coverage capabilities. To generate a code coverage report:

npm run test:coverage

This will:

1. Run all tests in the project
2. Generate a coverage report showing which parts of the code are covered by tests
3. Create detailed reports in the coverage directory

The coverage report includes:

• Statement coverage: percentage of code statements executed
• Branch coverage: percentage of control structures (if/else, switch) executed
• Function coverage: percentage of functions called
• Line coverage: percentage of executable lines executed

Coverage thresholds are set to 70% for statements, branches, functions, and lines. If coverage falls below these thresholds, the test command will fail.

To view the detailed HTML coverage report, open coverage/lcov-report/index.html in your browser after running the coverage command.

Running the MCP server in development mode with nodemon

Run the MCP server with nodemon and the DEBUG environment variable:

• The server is restarted whenever changes are detected on the source code.
• Debug output is enabled.

Using command line options

npm run dev -- --apikey <APIKEY> --url <URL>

Using environment variables

APIKEY=<APIKEY> URL=<URL> npm run dev

Environment variables

Name	Description
APIKEY	API key to access the decision runtime of either IBM Decision Intelligence or IBM Automation Decision Services
DEPLOYMENT_SPACES	Optional comma-separated list of deployment spaces to scan (default: development)
DEBUG	When the value is true, the debug messages are written to the stderr of the MCP server
PASSWORD	Password to access the decision runtime of IBM Automation Decision Services with basic authentication
RUNTIME	Optional target decision runtime: DI (default) or ADS
TRANSPORT	Optional transport protocol: STDIO (default) or HTTP
URL	Base URL of the decision runtime
USERNAME	Username to access the decision runtime of IBM Automation Decision Services either with basic authentication or Zen API key

License

Apache 2.0

Notice

© Copyright IBM Corporation 2025.