MCP Server

The ControlUp Model Context Protocol (MCP) server provides a standard interface for connecting your AI agent to your ControlUp products. MCP enables AI agents to invoke product-specific tools and operations in a structured and consistent way. If you already use an AI agent, such as Claude Code or Cursor, you can connect it to the ControlUp MCP server to access ControlUp information from within your own AI agent.

The ControlUp MCP server is a unified server for all supported ControlUp products and modules. You can connect to it in either of two ways:

• ControlUp-hosted MCP server: ControlUp runs the server for you. You connect your AI agent to a regional URL. The
• Self-hosted MCP server: You run the server locally, on the same computer as your AI agent.

What is an MCP server?

An MCP server exposes a set of product-specific tools to AI agents through the MCP protocol. AI agents use these tools to perform context-aware actions without a manual API integration. For example, instead of writing a script that calls the ControlUp API, you can ask your AI agent a question in plain language, and the agent calls the relevant ControlUp tools to answer it.

The ControlUp MCP server:

• Exposes tools for ControlUp products, such as ControlUp for VDI, ControlUp for Desktops, Compliance, and Workflows.
• Uses your ControlUp API key for authentication.
• Communicates with AI agents through standard transports (HTTP for the hosted server, stdio for the self-hosted server).

Benefits

• Unified integration: One MCP server supports all ControlUp products.
• Scalable workflows: Tools can be combined in a single prompt session.
• Consistent experience: The same protocol is used across all products.
• Flexible deployment: Use the ControlUp-hosted server with no local installation, or run the server yourself.

Security considerations

The ControlUp MCP server uses your ControlUp API key to authenticate and perform operations on behalf of your AI agent. The information you can access through the MCP server depends on the permissions of the ControlUp user who created the API key.

When you use a public LLM provider, data returned by ControlUp MCP tools is sent to that provider. This is the same as manually pasting sensitive data into a public AI service. Review the data policies of your AI agent provider before you connect it to the ControlUp MCP server.

Choose how to connect

Prerequisites

Before you start, make sure you have:

• A supported AI agent that can connect to MCP servers. We strongly recommend using only privately licensed AI agents.
• A ControlUp API key. Learn how to create one.
• For the self-hosted server only: your Organization ID, which you can find on the API Key Management page, and Node.js 18 or later installed on the computer where your AI agent runs.

Every user who wants to connect to the ControlUp MCP server must complete these steps on their own AI agent.

Option 1: Connect to the ControlUp-hosted MCP server

Step 1: Select your region

ControlUp runs the MCP server in four regions. Use the URL for your organization's region.

Your organization is identified from your API key, so you do not need to provide an Organization ID.

Step 2: Add the server to your AI agent

The hosted server requires one HTTP header:

Claude Code

Run the following command, replacing the URL with your regional URL and YOUR_API_KEY with your API key:

claude mcp add --transport http controlup https://mcp.us.controlup.com/mcp --header "api-key: YOUR_API_KEY"

Alternatively, add the following to your project's .mcp.json file:

{
  "mcpServers": {
    "controlup": {
      "type": "http",
      "url": "https://mcp.us.controlup.com/mcp",
      "headers": {
        "api-key": "YOUR_API_KEY"
      }
    }
  }
}

Other AI agents

Add a remote (HTTP) MCP server in your agent's MCP settings. Enter your regional URL and add the api-key header. The exact settings vary by agent, so refer to your agent's documentation for how to add a remote MCP server with custom headers.

Step 3: Verify the connection

Restart your AI agent, then confirm that the controlup server appears in its list of MCP servers and that its tools are listed. In Claude Code, run /mcp to see the status of your MCP servers.

Optional: Test your connection with Postman or curl

You can test your API key and region URL outside of an AI agent.

Postman

1. Create a new request, set the method to POST, and enter your regional URL.

2. On the Headers tab, add:

   Content-Type: application/json
   Accept: application/json, text/event-stream
   api-key: YOUR_API_KEY
   

3. On the Body tab, select raw and JSON, and enter:

   {
     "jsonrpc": "2.0",
     "id": 1,
     "method": "tools/call",
     "params": {
       "name": "platform__list-roles",
       "arguments": {}
     }
   }
   

4. Click Send. A successful response returns the roles in your organization.

curl

curl -X POST https://mcp.us.controlup.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "platform__list-roles",
      "arguments": {}
    }
  }'

To see all available tools, send the same request with "method": "tools/list" and without the params section.

Option 2: Run the self-hosted MCP server

Step 1: Configure the MCP server

Open your AI agent's settings and add the configuration below to the agent's MCP settings file. This file is usually called mcp.json and is available from the settings menu in most AI agents. Add the following JSON anywhere in that settings file.

Standard configuration (enables all ControlUp products)

Use this configuration to automatically enable tools for all supported ControlUp products. This is the recommended default.

{
  "controlup": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@controlup-ai/mcp@latest"
    ],
    "env": {
      "API_KEY": "YOUR_API_KEY",
      "ORG_ID": "YOUR_ORG_ID"
    }
  }
}

• Automatic installation: You do not need to install the package manually. The npx command fetches and runs the latest version of @controlup-ai/mcp when the agent starts.
• Credentials: Replace YOUR_API_KEY and YOUR_ORG_ID with your ControlUp values.

Advanced configuration (filter specific products)

To load tools only for specific ControlUp products, add the DOMAINS environment variable with a comma-separated list of product identifiers, in quotation marks. The following example loads DEX Platform, ControlUp for Desktops, and ControlUp for VDI:

{
  "controlup": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@controlup-ai/mcp@latest"
    ],
    "env": {
      "API_KEY": "YOUR_API_KEY",
      "ORG_ID": "YOUR_ORG_ID",
      "DOMAINS": "platform,cu4d,vdi"
    }
  }
}

If you omit DOMAINS, the server loads tools for all products. If you specify it, the server loads tools only for the listed products. See Product modules and identifiers.

Step 2: Start the agent

1. Save your JSON configuration in your AI agent settings.
2. Restart your AI agent.
3. Confirm that the MCP server starts and that the tools for the enabled products appear in your list of MCP servers. Your agent should display log entries indicating MCP startup and tool discovery.

Product modules and identifiers

Tools are grouped by product module. Tool names use the format identifier__tool-name, for example cu4c__list-devices or vdi__get-triggers.

For the self-hosted server, use these identifiers in the DOMAINS variable. Identifiers are case sensitive.

The ControlUp MCP server exposes read-only tools only. Your AI agent can retrieve information from ControlUp but cannot create, change, or delete anything.

Example interactions

After you connect, ask your AI agent a question in plain language. The agent selects and calls the relevant tools. For example:

• "List the roles in my organization."
• "Summarize audit log entries for the past 24 hours."

The agent can combine tools from several products to answer a single request.

Troubleshooting