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.

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:

{
  "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:

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.

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 for what that covers.