MCP Server

UTMStack v12 includes an MCP server. MCP (Model Context Protocol) is an open standard that lets AI tools, such as AI chat apps and coding assistants, call another system's functions. Through it, an AI client you trust can search your logs and alerts, work on alerts and incidents, build dashboards, manage response flows and more, with the same sign-in and permissions as the web console. The built-in SOC-AI assistant uses the same server.

At a glance

The health check answers, for example:

{"enabled": true, "tools_registered": 141, "server_version": "v1", "server_name": "<your server name>"}

tools_registered is the number of tools your server offers (141 in UTMStack v12.0.2). server_name is the server name chosen at installation. The Overview page shows the same number in the System health card, as SOC-AI engine.

Sign in

Every request needs one of these headers. Requests without a valid one are refused.

The AI client acts as the user who owns the token or the key, with that user's permissions. Create a dedicated user with only the permissions the AI client needs, and give it its own key.

On a multi-tenant installation:

• Use the tenant's own address (its domain) in the MCP address. An API key works only on its owner's tenant domain.

• The instance operator, signed in with an access token, can add X-Tenant-Id: <tenant id> to act inside a tenant that has granted Full access support access. Read only support access does not work for MCP, because every MCP request is a POST and read-only support allows only reading requests. An API key cannot switch tenant.

Connect an AI client

Any AI client that supports remote MCP servers over Streamable HTTP and lets you add a request header can connect. UTMStack signs clients in with a header (Utm-Api-Key or Authorization); it does not offer OAuth sign-in for MCP. There is no local (stdio) program to install on the UTMStack side.

Step 1: Create a user and an API key

1. In Configure > Team, create a user for the AI client, for example [email protected], with the narrowest role that does the job. A Viewer can only read; an Analyst can also change alerts, incidents, dashboards and flows. An API key is created by the user it belongs to, and creating one needs the apikey.write permission, which of the built-in roles only Administrator has. So give the user a custom role with the permissions the client needs plus apikey.write. See Roles and Permissions.

2. Sign in as that user, go to Configure > Settings > API Keys, click New API key, fill in a Name (for example claude-desktop) and, if you can, the Allowed IPs of the computer that runs the client. Click Create key and copy the secret. See Authentication and API Keys.

API keys need the Enterprise licence. Without it, you can test with an access token from POST /api/v1/auth/login (header Authorization: Bearer <token>), but it expires after one hour.

Step 2: Check that the server answers

From the computer that will run the AI client:

curl -s -H "Utm-Api-Key: <key>" https://<your UTMStack address>/api/v1/mcp/health

You should get {"enabled": true, "tools_registered": 141, ...}. If you get an error, fix it first with the Troubleshooting table below; the AI client will fail the same way and usually with a less clear message.

Step 3: Add UTMStack to your client

In every example, replace <your UTMStack address> with your server's address (on a multi-tenant installation, your tenant's address) and keep the key out of shared files: use an environment variable or the client's secret prompt, as shown.

claude mcp add --transport http --scope user utmstack 
  https://<your UTMStack address>/api/v1/mcp 
  --header "Utm-Api-Key: <key>"

{
  "mcpServers": {
    "utmstack": {
      "type": "http",
      "url": "https://<your UTMStack address>/api/v1/mcp",
      "headers": {
        "Utm-Api-Key": "${UTM_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "utmstack": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<your UTMStack address>/api/v1/mcp",
        "--header",
        "Utm-Api-Key:${UTM_API_KEY}"
      ],
      "env": {
        "UTM_API_KEY": "<key>"
      }
    }
  }
}

{
  "mcpServers": {
    "utmstack": {
      "url": "https://<your UTMStack address>/api/v1/mcp",
      "headers": {
        "Utm-Api-Key": "${env:UTM_API_KEY}"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "utm-api-key",
      "description": "UTMStack API key",
      "password": true
    }
  ],
  "servers": {
    "utmstack": {
      "type": "http",
      "url": "https://<your UTMStack address>/api/v1/mcp",
      "headers": {
        "Utm-Api-Key": "${input:utm-api-key}"
      }
    }
  }
}

Step 4: Try it

Ask a read-only question first, for example "How many alerts are open in UTMStack, grouped by severity?". The client should call a tool such as alerts.count_open or store.search. Then open Configure > Settings > App Audit Logs: each tool call is listed with the user of your API key.

Certificates

AI clients check the server's HTTPS certificate and refuse the self-signed certificate a new UTMStack server uses. The clean fix is a certificate from a public certificate authority, or from your company's own authority that your computers already trust. See SSL Certificate.

If your certificate comes from your company's own authority and a client still refuses it, point the client to that authority's certificate. Clients built on Node.js, including Claude Code and the mcp-remote bridge, read the environment variable NODE_EXTRA_CA_CERTS:

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

In the Claude Desktop configuration, add it to env next to UTM_API_KEY. Do not switch certificate checking off: the key would then go to whoever answers on that address.

Permissions and audit

• Every tool checks the same permission as the matching page or API call (for example alerts.write to change an alert). Some tools also need the instance operator role or a licence. A refused call answers "permission denied: …".

• Every tool call, allowed or refused, is written to the audit log with the event type MCP_TOOL_CALL (Configure > Settings > App Audit Logs).

• Tools that return lists give 50 items by default and at most 500.

Tools

These are the tools registered in UTMStack v12.0.2. "Needs" is the permission the signed-in user must have.

Alerts (17)

Incidents (16)

Log and alert data (7)

Log Explorer (7)

Automated response (SOAR) (14)

Dashboards (11)

Compliance (18)

Detection rules and pipelines (17)

Data sources (5)

Settings, audit and system (13)

Changes across tenants (instance operator only) (16)

In the tools that change many tenants at once, list the target tenants by their ids. The option to target all tenants does not work in UTMStack v12.0.2.

What the MCP server does not do

• Start a response flow by hand. Use Trigger flow in the web console or the SOAR API.

• Manage integrations, users, roles, API keys, identity providers, notifications or tenants. These tools are not offered in UTMStack v12.0.2.

Resources

Resources are read-only documents an AI client can read for background.

Prompts

Troubleshooting

Check the health address with curl (Step 2 above) before you look at the client: it gives the clearest error.

Turning it off

The MCP server is on by default, and the web console has no switch for it. The built-in SOC-AI assistant works through it, so AI features need it.

Related pages

• SOC-AI Assistant

• Authentication and API Keys

• API Quick Start

• Building a Flow