How to connect an AI assistant to the Control-M MCP server

Control-M MCP Server is a standards-based interface that lets AI agents and assistants interact with Control-M workflows and automation services. The Control-M SaaS documentation says it is built on the Model Context Protocol, so an assistant can discover Control-M capabilities and run actions such as triggering jobs, checking workflow status, and investigating failures. You use your own corporate AI tools and models. You can also attach this server to a tool registry or MCP gateway beside other MCP servers, so one prompt can use more than one toolset.

It is a Preview feature. You can raise Support cases for Preview features at Impact Level 3 and 4. Preview functionality might be modified in the future. BMC recommends that you use this feature in non-production environments.

Limits before you connect

The page states these limits before any client sample:

The server can connect to a maximum of five AI assistants in parallel.
It supports up to 60 requests per minute.
It does not run Forecast jobs.

Authorization to perform an action is defined in User and Role Authorizations. A token does not replace those role settings.

The server supports elicitation, which prompts the user to confirm an action before it is executed. If you want that confirmation, your assistant must also support elicitation. The procedure says to verify that before you begin.

Token and annotation headers

The samples grant access with an API token in the HTTPS header. The settings table says you can create that token with the authentication API it links, or in Control-M Web as described in Creating an API Token. This page names that call and does not show its syntax, so the syntax is not repeated here. The token grants access permissions to specific roles for a period you can pre-define. The page says the header can accept an API token, and it recommends the credential manager your organization supports rather than a pasted secret. The samples read the token from an environment variable and place it in the header shown in each block.

Annotation-Subject and Annotation-Description are optional. You must add both if annotations are enabled, as described in Annotation Input. The strings in the samples are examples. The subject is printed as "Control-M MCP Sever Demo".

Add the server

Documented clients are Claude Desktop, Visual Studio, and Cursor. The Visual Studio example is labeled Visual Studio code. The configuration process varies by vendor. Adding the server generates a JSON file with the configured settings on the assistant.

Enable Control-M MCP Server in Control-M Automation API. The procedure points to a system-settings reference for that enable action and does not print an invocation on this page. Open that reference. Do not guess a command line.
On the assistant, add Control-M MCP Server with the settings in the sample for that client.
Verify in the assistant that Control-M MCP Server is connected. A list of MCP tools appears when it is connected.
Type a prompt. Examples from the page are in the last section.

The client samples and the settings table do not print the same host. The JSON examples include a port segment in the host. The settings table format for url does not. Fill in your tenant and zone, and include a port only if your host uses one. Do not invent a hostname. If the live page and these blocks disagree, follow the live page.

Claude Desktop

This sample is the local-command example. The block below is copied as fetched, including trailing backslashes on the args lines, a header entry with no colon, and no comma after the token line. Do not repair it from memory.

"controlm": {
   "command": "C:\\PROGRA~1\\nodejs\\npx.cmd",
   "args": [\
      "-y", "mcp-remote",\
       "https://<tenant-name>-aapi.<zone>.controlm.com:port/automation-api/mcp/message",\
       "--header" {\
          "x-api-key": "${env:CTM_API_TOKEN}"\
          "Annotation-Subject": "Control-M MCP Sever Demo",\
          "Annotation-Description": "This is a test message from Control-M MCP Server"\
        }\
      ]
}

If you copy that example, verify two things the page requires. Node.js is installed on the AI assistant. The command parameter value must not contain spaces. The sample command is the short path in the block. The page's illustration of a spaced path misspells the Node.js folder and the executable, and says that form must be rewritten to the short path. Use your real Node.js executable in a space-free path.

Visual Studio

The Visual Studio code sample is remote HTTP, not a local command. Copied as printed, it has no comma after the token line. The sample type is http. The settings table prints the valid value as HTTP.

"controlm": {
    "url": "https://<tenant-name>-aapi.<zone>.controlm.com:port/automation-api/mcp/message",
    "type": "http",
    "headers": {
       "x-api-key": "${env:CTM_API_TOKEN}"
       "Annotation-Subject": "Control-M MCP Sever Demo",
       "Annotation-Description": "This is a test message from Control-M MCP Server"
     }
}

Cursor

The Cursor sample is stateless HTTP. It is the sample that adds Content-Type and Accept.

"controlm": {
   "url": "https://<tenant-name>-aapi.<zone>.controlm.com:port/automation-api/mcp/message",
   "type": "http",
   "headers": {
      "Content-Type": "application/json",
      "Accept": "application/json, text/event-stream",
      "x-api-key": "${env:CTM_API_TOKEN}",
      "Annotation-Subject": "Control-M MCP Sever Demo",
      "Annotation-Description": "This is a test message from Control-M MCP Server"
   }
}

If you use stateless HTTP in Cursor, the page says you must add Content-Type and Accept in the headers. The note under that step sets Accept to application/json. The JSON sample sets Accept to application/json, text/event-stream. Both appear on the page. Use the value the live page shows for the client you are configuring. Do not merge them into a third string.

What the fields mean

url is the Control-M MCP Server address for a stateless HTTP connection, in the host format the settings table describes.
type must be a remote HTTP server that implements the MCP protocol. Valid value: HTTP.
The token header defines an API token for specific roles, for a period you can pre-define.
Annotation-Subject is the annotation subject. It is optional, and required if annotations are enabled.
Annotation-Description is the free-text annotation. It is optional, and required if annotations are enabled.

Unknown from this page: the token's default lifetime, which roles it must include, and the full text of the enable action. Those are only named here.

Confirm tools, then prompt

A list of MCP tools appears when the server is connected. The page does not name those tools. If the list is missing, the server is not connected yet. Recheck the enable setting, the host, the token header, and, for Cursor stateless HTTP, Content-Type and Accept.

The prompts below are the page's samples, not evidence that those job names exist in your environment. A status or log prompt is the safer first check. Job-action prompts still follow user and role authorization. Elicitation asks for confirmation only when the assistant supports it.

Job status:

What is the current status of the "Daily_Billing_Report" job?
Show me all jobs that failed in the last 2 hours.
Are there any jobs currently running in the PROD environment?
Which jobs ended not-OK today?

Logs and output:

Show me the log for the last run of the "ETL_Load_Customers" job.
What was the output of "File_Transfer_EU" job that ran this morning?
Why did the "Archive_Orders" job fail? Show me the relevant log lines.

Job actions:

Rerun the "Daily_Billing_Report" job.
Hold the "Nightly_Backup" job until further notice.
Release the "ETL_Load_Customers" job so it can run.
Set the "Archive_Orders" job to OK.

What to do next

Open the Control-M SaaS MCP Server page, enable the server through the system-settings reference that page links, and create an API token the way that page describes. Paste the Claude Desktop, Visual Studio, or Cursor block only after you compare punctuation and the Cursor Accept value with the live sample. Confirm that MCP tools appear, then try one status or log prompt from the table in a non-production environment. Stay inside five parallel assistants and 60 requests per minute, and do not expect Forecast jobs to run.

Sources

Control-M MCP Server