Maximo MCP server overview

The Maximo® MCP server enables AI agents to access Maximo Manage data and functionality through standardized tool calls. The Maximo MCP server runs as a pod in Red Hat® OpenShift®. You configure the server by editing environment variables in the pod deployment settings. The server automatically synchronizes with Maximo Manage to maintain an up-to-date list of available tools.

The Maximo MCP pod remains in an unready waiting state until Maximo Manage is in a ready state, at which point the pod conducts a full tools refresh and assumes a ready state. If at any point in the pod's lifecycle, Maximo Manage becomes unready, the Maximo MCP pod resumes an unready state and waits for Maximo Manage to get into a ready state again. For example, Maximo Manage is unready if the ManageWorkspace CR is unready.

The Maximo MCP pod pulls a list of MCP tools on pod startup, and checks for updates, such as modifications to existing tools or new tools, at the frequency defined in the POLLING_FREQUENCY environment variable. You can edit this frequency. To force a refresh, in Red Hat OpenShift, restart the MCP pod. Restarting the pod does not affect tools but does affect in progress tool calls. Maximo Manage acts as a single source of truth for the MCP tools list. The MCP server will not be more current than Maximo Manage.

By default, the Maximo MCP server supports the following features and capabilities:

Maximo Assistant: In Maximo Application Suite 9.2, the agentic Maximo Assistant is supported by the ALM-agent AI agent. The agent uses the Maximo MCP server to answer complex, multi-step questions by chaining together multiple tool calls. For more information, see Connecting external AI agents to the Maximo MCP server.
Custom tools: Custom tools created using Maximo Manage automation scripts, object structures, or workflows are deployed to the MCP server. These tools can access any data that you grant them access to as part of their settings. For more information, see Creating custom tools for AI assistants.
External agent connections: External AI agents can connect to the Maximo MCP server using a public-facing route URL available in Red Hat OpenShift. Authentication is required through either an API key header or JSON web token. For more information, see Connecting external AI agents to the Maximo MCP server.

Environment variables

The Maximo MCP pod contains environment variables that control its behavior. To access the variables, complete the following steps:

In Red Hat OpenShift, navigate to Workloads > Deployments.
Find and select the instance_ID-mcp deployment. A list of variables is available on the Environment tab.

Do not change the following variables. They manage the internal state of the Maximo MCP server.

MXE_MASDEPLOYED
MXE_MASINTERNALAPI
APP_API_URL
APP_ID
COREIDP_OIDC_URL
CLIENT_ID
CLIENT_SECRET
OPENAPI_EP
GET_ETAG_EP
CPU_LIMITS_MCP

You can change the following variables. You might change these variables to tune the Maximo MCP server to work better with your use case.

POLLING_FREQUENCY: The frequency, in seconds, at which the Maximo MCP pod polls Maximo Manage for updates to the tools list. By default, it polls every 10 minutes.
TOOL_RESPONSE_TIMEOUT: The timeout, in seconds, used for an MCP tool call before a timeout error occurs. By default, the timeout is 10 minutes.

MCP Inspector

Use the MCP Inspector tool to view and debug tools on the Maximo MCP server. For more information, see Connecting external AI agents to the Maximo MCP server.

Example: Calling the Data retrieval tool

You can call MCP tools by using the MCP Inspector or using an HTTP call. The following example tool calls are for the Data retrieval tool. Before calling a tool, the tool must be available. For example, if you are calling one of the default tools, it must be enabled as AI configurations in Maximo Manage.

To use the MCP Inspector, select the tool and in the Instances input field, specify the following JSON.


[
    {
      "utterance": "show me all work with priority 10"
    }
]

The output is a JSON object that has the following properties:

usage: The usage details of the tool.
predictions: The nl2oslc payload.


"usage": [
    {
      "output_token_count": 521,
      "model_type": "watsonx",
      "total_tokens": 6755,
      "input_token_count": 6234
    },
    {
      "output_token_count": 1000,
      "model_type": "sql_to_oslc",
      "total_tokens": 1000,
      "input_token_count": 0
    }
  ],
"predictions": [
    [
      {
        "total_timings": {
          "total_evaluation_time": "0:00:02.107259",
          "db_chain_evaluation_times": {
            "linking_times": {
              "domain_linking_time": "0:00:00.143481",
              "total_linking_time": "0:00:00.252876",
              "schema_linking_time": "0:00:00.109395"
            },
            "llm_time": {
              "prompt_evaluation_time": "0:00:01.984472"
            }
          },
          "total_explanation_time": "0:00:01.169694",
          "oslc_conversion_time": "0:00:00.040714"
        },
        "expected_count": 2,
        "projectiontemplate": "DFLTWOVIEW",
        "where": "wopriority=10",
        "api": "MXAPIWODETAIL",
        "allowed_count": 200,
        "explanation": "Retrieve the work order number (wonum), priority (wopriority), type (worktype), and location (worklocation) for all work orders where the priority equals 10.",
        "sql": " SELECT wonum, wopriority, worktype, worklocation FROM workorder WHERE wopriority = 10; "
      }
    ]
  ]

To get a list of hrefs from this output, copy the output and in the MCP Inspector, for the Data retrieval results tool, input the usage object in the usage input section and the predictions object in the predictions input section. The output is a JSON object with the following items:

member: A JSON array of the returned objects from the nl2oslc query.
href: The href of the object structure that was used to make the query.
responseInfo: Metadata about the response, including totalPages, href of the total collection, and pagenum of the current results.


{
  "member": [
    {
      "href": "http://root/maximo/oslc/os/mxapiwodetail/string",
      "record_descriptor": null,
      "owner": "NAME",
      "parent": null,
      "status_description": "Approved",
      "wopriority": 5,
      "problemcode": null,
      "reportdate": "2019-06-18T14:21:00-04:00",
      "description": "Request for OS upgrade to Windows XP",
      "jpnum": null,
      "wonum": "1087",
      "_rowstamp": "405698",
      "failurecode": null,
      "assetnum": null,
      "istask": false,
      "siteid": "BEDFORD",
      "location": null,
      "status": "APPR"
    },
    ...
  ],
  "href": "http://root/maximo/oslc/os/MXAPIWODETAIL",
  "responseInfo": {
    "totalPages": 1,
    "href": "http://root/maximo/oexpslc/os/MXAPIWODETAIL?ignorecollectionref=1&recdesc=1&inlinedoc=1&lean=1&oslc.pageSize=100&_dropnulls=0&querytemplate=DFLTWOVIEW&avoidprivateattrs=1&collectioncount=1&oslc.where=owner%3D%22-personid-%22",
    "pagenum": 1
  }
}

To use HTTP calls instead of the MCP Inspector, use the external MCP route to make a POST tool call to the Maximo MCP server. For example, for the APISCHEMA tool, within the payload, you must specify the jsonrpc version, the tools/call value for method, and a params object, which contains the name of the tool and its input arguments. All tool calls are POST calls.


curl -X POST "MCP server route URL" \
  -H "apikey: Maximo Manage API key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "apischema",
      "arguments": {
        "api": "MXAPIASSET"
      }
    },
    "id": 1
  }'

The response is a server-sent event (SSE) format message with the event type as message and the data field containing the tool output in the json-rpc 2.0 format. The json-rpc object contains the jsonrpc version, the request identifier, and the result object, which contains a sub-object content array and a boolean isError. The content array contains a content type string and a text string, which contains the actual response content of the tool call.