di-mcp-server-experimental

v0.0.3

Published

12 days ago

[![Build and test](https://github.com/DecisionsDev/di-mcp-server/actions/workflows/build.yml/badge.svg)](https://github.com/DecisionsDev/di-mcp-server/actions/workflows/build.yml) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LI

0High
0Medium
0Low

jeanfi-ibm

MCP server for IBM Decision Intelligence and IBM Automation Decision Services

npm Downloads

flowchart LR
   client("AI Assistant <br><br>(Claude, Watsonx Orchestrate, etc.)") -- MCP --> server("Decision Intelligence<br>MCP Server")
   server -- HTTPS --> runtime("IBM Decision Intelligence <br>or IBM ADS <br><br>Decision Runtime")

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.

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
Trusted automated decisions in Agentic application with IBM Decision Intelligence and MCP: this video shows how an agentic application can leverage automated decision services defined and hosted in the IBM Decision Intelligence platform to make accurate and explainable decisions
Enrich your watsonx Orchestrate chat experience with IBM Decision Intelligence: step by step instructions to use decisionning capability in IBM watsonx Orchestrate.

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.

For IBM Decision Intelligence

Create the MCP server using decisions deployed in IBM Decision Intelligence:

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

For IBM Automation Decision Services

Zen APIKey authentication

Create the MCP server using decisions deployed in IBM Automation Decision Services using the Zen APIKey authentication:

npx -y di-mcp-server --authentication-mode zenapikey --zen-username <YOUR_ZEN_USERNAME> --zen-apikey <YOUR_ZEN_API_KEY> --url https://myads-hostname/ads/runtime/api/v1

Basic authentication

Create the MCP server using decisions deployed in IBM Automation Decision Services using the basic authentication:

npx -y di-mcp-server --authentication-mode basic --basic-username <YOUR_USERNAME> --basic-password <YOUR_PASSWORD> --url https://myads-hostname/ads/runtime/api/v1

Command line syntax

Syntax of the command line:

npx -y di-mcp-server [--authentication-mode <AUTHENTICATION_MODE>] <CREDENTIALS> --url <RUNTIME_BASE_URL> [--transport <TRANSPORT>] [--deployment-spaces <DEPLOYMENT_SPACES>]

where

AUTHENTICATION_MODE (optional) is the authentication mode to access the decision runtime; either diapikey (default), zenapikey or basic respectively for authenticating with Decision Intelligence API key, Zen API key or basic credentials (i.e. username and password)
CREDENTIALS is one of the following options, depending on the chosen authentication mode:
- For DI API key authentication: --di-apikey <DI_API_KEY> where DI_API_KEY is the API key to access the decision runtime for Decision Intelligence.
- For Zen API key authentication: --zen-username <ZEN_USERNAME> --apikey <ZEN_API_KEY> where ZEN_USERNAME and ZEN_API_KEY are the Zen API key credentials to access the decision runtime for Automation Decision Services (see Authorizing HTTP requests by using the Zen API key)
- For basic authentication: --basic-username <BASIC_USERNAME> --basic-password <BASIC_PASSWORD> where BASIC_USERNAME and BASIC_PASSWORD are the basic authentication credentials to connect to the decision runtime for Automation Decision Services.
RUNTIME_BASE_URL is the base URL of the decision runtime REST API. For 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.
DEPLOYMENT_SPACES (optional) is a comma-separated list of deployment spaces to scan (defaults to development).
DECISION_SERVICE_IDS (optional) If defined, comma-separated list of decision service ids to be exposed as tools

The following environment variables can be used in addition to the command line options.

| CLI Option | Environment Variable | Description | |------------|---------------------|---------------------------------------------------------------------------------------------------------------| | --authentication-mode | AUTHENTICATION_MODE | Optional authentication mode to connect to the decision runtime: diapikey (default), zenapikey or basic | | --di-apikey | DI_APIKEY | Decision Intelligence API key | | --zen-username | ZEN_USERNAME | Zen username | | --zen-apikey | ZEN_APIKEY | Zen API key | | --basic-username | BASIC_USERNAME | Basic authentication username | | --basic-password | BASIC_PASSWORD | Basic authentication password | | --deployment-spaces | DEPLOYMENT_SPACES | Optional comma-separated list of deployment spaces to scan (default: development) | | --debug | DEBUG | When the value is true, the debug messages are written to the stderr of the MCP server | | --transport | TRANSPORT | Optional transport protocol: stdio (default) or http | | --url | URL | Base URL of the decision runtime |

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

The article Enrich your watsonx Orchestrate chat experience with IBM Decision Intelligence demontrates how to integrate the capability to discover and execute decisions in an IBM watsonx Orchestrate agent using the Decision Intelligence MCP server.

Specifying the APIKEY and URL environment variables

You can use the connection setting to specity the API key and URL environment variables.

Open the main menu, expand Manage, and then click Connections. The Connection settings opens.
Click Add new connection to launch the Add new connection wizard.
Enter the Connection ID and Display name fields, and then click Save and continue.
In the Configure draft connection panel:
- Select Key Value Pair as Authentication Type.
- Enter the Key and Value fields to define the DI_APIKEY environment variable.
- Click Add key value pair.
Enter the Key and Value fields to define the URL environment variable, and then click Connect.
When the draft connection is connected, click Next.
Similarly configure the live connection. When it is done, click Add connection.
In the Add MCP Server wizard:
- Select the display name corresponding to the connection you just configured.
- Enter the npx command WITHOUT the --di-apikey and --url arguments.
- Click Connect, and then click Done.

Integrating decision services into Claude Desktop

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

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

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",
                "--di-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": {
                "DI_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

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

In Cursor, click the cog wheel icon to open the Cursor settings.
Click Tools & Integration in the settings categories that are listed on the left.
Click + New MCP Server, to open Cursor's mcp.json configuration file.

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 with one of the following methods:

Using command line arguments:

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

Using environment variables:

{
    [..]
    "mcpServers": {
        "di-mcp-server": {
            "command": "npx",
            "args": ["-y", "di-mcp-server"],
            "env": {
                "DI_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 in the Cursor documentation.

Using custom tool names

When you integrate with MCP hosts, you might 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 in the following way:

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

Customizing tool names with the decision runtime 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

Technical details

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

License

Apache 2.0