---
title: Connect Your MCP Client
description: Create a ControlCom API key and connect Claude Code, Claude Desktop, Cursor, or any MCP client to the Builder MCP server.
source: https://documentation.controlcomtech.com/build/mcp/connect
---

# Connect Your MCP Client

Connecting takes two things: an API key scoped to your organization, and a small config block pasted into your MCP client.

> **Workflow Stage: Integrate**

## Create an API key

In ControlCom Connect, go to **Settings → API Keys → Create API Key**. After you create the key, the dialog shows three things:

* the **public ID**,
* the **secret**, shown once, so copy it now,
* a **ready-to-paste MCP client config block** with the secret already encoded.

The Builder MCP authenticates with API keys only. A user session or JWT token will be rejected, so always connect with a key created here.

## The generated config

The dialog produces a config block that looks like this, with your organization ID in the URL and the Base64-encoded `publicId:secret` already filled in:

```json
{
  "mcpServers": {
    "controlcom-builder": {
      "type": "http",
      "url": "https://api.controlcomtech.com/primary/v1/<organizationId>/mcp/builder",
      "headers": { "Authorization": "Basic <token>" }
    }
  }
}
```

The `Authorization` value is `Basic` followed by `base64("<publicId>:<secret>")`. Treat it like a password: anyone with this token has the same access to your organization that the key grants.

## Add it to your client

Paste the block into your client's MCP configuration file and merge it under `mcpServers`:

| Client         | Config file                                                       |
| -------------- | ----------------------------------------------------------------- |
| Claude Code    | `~/.claude.json`                                                  |
| Claude Desktop | `claude_desktop_config.json` (Settings → Developer → Edit Config) |
| Cursor         | `~/.cursor/mcp.json` (or Settings → MCP)                          |
| Other clients  | The client's equivalent `mcpServers` configuration                |

If the file already has an `mcpServers` object, add `controlcom-builder` alongside your existing entries rather than replacing the whole object. Restart the client after saving so it picks up the new server.

## Verify the connection

Once the client reconnects, the `controlcom-builder` server should list its tools. Ask your assistant something read-only, for example "list my asset types" or "list my devices." A successful response confirms the key, URL, and transport are all correct. A `401` means the key is missing, malformed, or a session token was used instead of an API key. See [Limits & troubleshooting](https://documentation.controlcomtech.com/build/mcp#troubleshooting).

## Model your first asset

With the client connected, a build follows a consistent discover → create → bind → verify pattern. You can run it as one natural-language instruction (*"Create a generator asset called 'Generator 1', bind its output-power variable from device GEN-01, and show me the current reading"*), and the assistant performs these steps:

1. `listAssetTypes` to reuse a label, or `createAssetType` for a new category such as "Generator."
2. `createAsset` with the resolved `typeId` (and an optional `parentId` to place it in the hierarchy).
3. `listDevices`, then `createVariable` on the right device with the correct `topicPropertyPath`.
4. `bindVariables` to attach the variable(s), then `getAssetBindings` to confirm.
5. Optionally `createAssetRelationshipType` + `createAssetRelationship` to wire functional edges like power flow.
6. `getCurrentReading` / `getDeviceStatus` to confirm the model reflects live data.

A multi-step request is planned once, approved once, then executed as a batch. Additive steps run without friction; anything destructive is restated and confirmed first. See the [safety model](https://documentation.controlcomtech.com/build/mcp#safety) for what that covers.