> For the complete documentation index, see [llms.txt](https://docs.buildings.ability.abb/collection/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildings.ability.abb/collection/for-developers/mcp/connect-your-client.md).

# Connect your client

Connect a compatible AI client to the BuildingPro Suites MCP server.

Connect an AI client to BuildingPro Suites with an API key. The server uses Streamable HTTP at

```http
https://buildings.ability.abb/suites/mcp
```

## Before you start

* An MCP-compatible client that supports Streamable HTTP and the `X-API-Key` header.
* An API key for the BuildingPro Suites tenant you want to access.
* The MCP endpoint: `https://buildings.ability.abb/suites/mcp`.

For key setup, see [Create API Keys](https://docs.buildings.ability.abb/collection/platform/platform-core/api-keys.md#create-api-keys). Ask your administrator for a key with only the permissions your task needs.

An API key identifies its tenant and resource permissions. It does not identify the person signed in to the AI client. Keep the key out of prompts, shared configuration files, and source control.

## Add the server

Use the MCP endpoint `https://buildings.ability.abb/suites/mcp`.

Choose Streamable HTTP if your client asks for a transport. This server does not support `stdio` or `SSE`. You can usually leave extra optional connection fields empty.

1. Add the server URL to your AI client.
2. Set the request header `X-API-Key` to your API key.
3. Start the server connection.
4. Ask the client to list sites without changing anything.
5. Confirm that the returned sites belong to the intended tenant.

Do not put the API key in the URL. Do not send it over public HTTP.

## Configure a client

Use these settings in the client configurations below.

| Setting     | Value                                      |
| ----------- | ------------------------------------------ |
| Server URL  | `https://buildings.ability.abb/suites/mcp` |
| Transport   | `Streamable HTTP`                          |
| HTTP header | `X-API-Key: <your API key>`                |

{% tabs %}
{% tab title="General" %}
Choose a client that supports Streamable HTTP and custom request headers.

{% stepper %}
{% step %}

### Set the server URL

Enter `https://buildings.ability.abb/suites/mcp`.
{% endstep %}

{% step %}

### Select the transport

Choose `Streamable HTTP`.
{% endstep %}

{% step %}

### Add the API key

Set the `X-API-Key` request header to your API key.
{% endstep %}
{% endstepper %}

Do not put the API key in the URL or send it over public HTTP.
{% endtab %}

{% tab title="Claude web or Desktop" icon="claude" %}
For now you can only connect to our MCP server by adding it as a custom connector. See [Claude Desktop custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for detailed instructions.
{% endtab %}

{% tab title="ChatGPT web" icon="openai" %}
ChatGPT web's custom MCP connection does not currently support this server's `X-API-Key` authentication. You cannot connect with an API key until we support a compatible authentication method.

Use OpenAI Codex with the configuration in the next tab. See [OpenAI MCP authentication](https://developers.openai.com/plugins/build/auth) for current client requirements.
{% endtab %}

{% tab title="Claude Code" icon="claude" %}
Set `BPRO_MCP_API_KEY` in your local environment or secret manager. Add this entry to `.mcp.json`:

```json
{
  "mcpServers": {
    "bpro-suites-mcp": {
      "type": "http",
      "url": "https://buildings.ability.abb/suites/mcp",
      "headers": {
        "X-API-Key": "${BPRO_MCP_API_KEY}"
      }
    }
  }
}
```

Keep the key value outside `.mcp.json`. Start Claude Code from an environment where `BPRO_MCP_API_KEY` is set, then check the connection in `/mcp`.

See [Claude Code MCP setup](https://code.claude.com/docs/en/mcp) for other configuration options.
{% endtab %}

{% tab title="OpenAI Codex" icon="openai" %}
Set `BPRO_MCP_API_KEY` in your local environment or secret manager. Add this entry to `~/.codex/config.toml`:

```toml
[mcp_servers.bpro-suites-mcp]
url = "https://buildings.ability.abb/suites/mcp"
env_http_headers = { "X-API-Key" = "BPRO_MCP_API_KEY" }
```

`env_http_headers` names the environment variable that contains the key. It does not contain the key itself. Restart Codex and check its MCP server list.

See [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp).
{% endtab %}

{% tab title="VS Code" icon="vscode" %}
Add this entry to `.vscode/mcp.json`:

```json
{
  "servers": {
    "bpro-suites-mcp": {
      "type": "http",
      "url": "https://buildings.ability.abb/suites/mcp",
      "headers": {
        "X-API-Key": "${input:bpro-suites-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "bpro-suites-api-key",
      "description": "BuildingPro Suites API key",
      "password": true
    }
  ]
}
```

VS Code prompts for the key without displaying it. Start the server from the MCP view and confirm it connects.

See [Add MCP servers in VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
{% endtab %}
{% endtabs %}

## Choose tools

If you omit `toolsets`, your client discovers all tools exposed by the MCP server. To limit the list, add a `toolsets` query parameter to the MCP URL:

```
https://buildings.ability.abb/suites/mcp?toolsets=assets,data
```

Available toolsets are `context`, `admin`, `alarms`, `assets`, `data`, `dashboards`, `rules`, and `sites`. You can select more than one.

Toolset selection only changes which tools the client sees. It does not grant permissions or make a write-capable key read-only. The API key still authorizes each operation.

These mainly provide a way to have a more fine-grained control over context usage.

## Check the connection

Ask the client to list sites or some specific assets. Request a read-only result and do not include the API key in your prompt.

Ask the client to list your sites and confirm the tenant before requesting data. If the sites do not match, stop and check the API key (or ask an administrator to verify it). The `whoami` tool can help verify the identity associated with the API key.

If a client cannot connect, check the URL, the `X-API-Key` header, the key's expiration, and the permissions assigned to the API key.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.buildings.ability.abb/collection/for-developers/mcp/connect-your-client.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
