MCP

The processor has a built-in Model Context Protocol (MCP) server. An AI assistant that supports MCP can use it to see your locations, run commands and manage schedules, with the same API key, permissions and licences as the REST API.

What you need

The API Licence, and a Manager Licence or a User App Licence.
An API key. Use Read only unless the assistant should be able to change things.
An MCP client on the site network that can send a custom header, or a bridge that does. Keys and the MCP endpoint aren't reachable from the internet, so an assistant that runs in the cloud can't connect.
The processor's certificate, trusted on the computer that runs the client.

The endpoint

https://<processor address>:8443/mcp

Use the processor's address and admin HTTPS port. See Ports and network. Every request carries the key in the X-Api-Key header. The endpoint takes no other kind of sign-in: a staff sign-in token is refused with 401.

The server is stateless. It takes one JSON-RPC 2.0 message in each POST and answers with application/json. It keeps no session and never streams, so GET and DELETE on /mcp answer 405 with Allow: POST. Batches aren't supported.


Protocol versions	`2025-06-18`, `2025-03-26` and `2024-11-05`. A client that asks for another is offered `2025-06-18`.
Methods	`initialize`, `ping`, `tools/list` and `tools/call`. A notification, such as `notifications/initialized`, is answered 202 with no body.
Capabilities	Tools only.
Server version	The processor's program version.

Trust the processor's certificate

The processor serves HTTPS with its own certificate authority. Until the computer trusts it, a client refuses the connection with a certificate error.

Download the certificate from Settings → Deployment → Downloads, or from http://<processor address>:8080/box-ca.crt. See Downloads.
Trust it on the computer that runs the MCP client. The steps for a Mac and for Windows are under Certificate.
Or, for a program built on Node.js such as the desktop example below, point NODE_EXTRA_CA_CERTS at the file. It trusts the certificate for that program only, and it's the simplest option.

If the site uses its own certificate on the admin port, trust that certificate's authority instead. See Certificate.

Connect a desktop client

Most desktop MCP clients start local programs and don't send custom headers to a remote server themselves. The mcp-remote program bridges the two. This example is for Claude Desktop; other desktop clients use the same command, args and env fields in their own MCP settings. It was tested with mcp-remote 0.14.3.

Save the key on its own line in a file that only you can read, for example centro-headers.txt:
```
X-Api-Key: cbk_your-key-here
```
On a Mac or Linux, run chmod 600 centro-headers.txt so other users of the computer can't read it.
Save the processor's certificate next to it, for example as centro-box-ca.crt.

Add the server to the client's MCP settings. For Claude Desktop, go to Settings → Developer → Edit Config:

{
  "mcpServers": {
    "centro-system-manager": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://192.168.10.22:8443/mcp",
        "--transport",
        "http-only",
        "--header-file",
        "/Users/you/centro-headers.txt"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "/Users/you/centro-box-ca.crt"
      }
    }
  }
}

Restart the client. The server's eleven tools appear in its tool list.

note

mcp-remote needs Node.js 18 or later on the computer. A key in --header-file stays out of the process list, where other users of the computer could read it. If you'd rather put the key in the settings file, use "--header", "X-Api-Key:${CENTRO_API_KEY}" and put "CENTRO_API_KEY" in env. Mind who can read that file.

To make two servers with different permissions, give each its own name and its own key. For example, centro-read with a Read only key and centro-control with a Read and control key. Then the assistant can only change things through the one you chose to give it.

Then ask the assistant something the key allows, such as "List my locations and tell me which ones have a connection that is offline."

Tools

The assistant sees eleven tools. Each is allowed only when the key has the permission shown and the licences allow the function.

Tool	What it does	Permission it needs
`list_locations`	Lists locations with their id, name, tags, group, whether they can be controlled and how many connections serve them. Takes `search`, `tag` and `take` (1 to 500, 100 if you leave it out).	See locations and what is happening in them
`get_room_state`	Reads a location's climate, lighting, media, scene, shades, door, occupancy and service state. Needs `locationId`.	Same
`get_room_notifications`	Lists a location's live notifications, newest first. Takes `locationId`, and optionally `take` and `severity`.	Same
`get_available_commands`	Lists the capabilities a location can be commanded on and the connection that carries each. Needs `locationId`.	See schedules, and what each location can be sent
`set_room_command`	Runs a command in a location. Takes `locationId`, `capability`, `action`, and the values to set in `climate`, `lighting`, `housekeeping`, `scene` or `shades`.	Send commands to locations
`list_schedules`	Lists the schedules, optionally only those with one of the `tags` given.	See schedules, and what each location can be sent
`get_schedule`	Reads one schedule. Needs `id`.	Same
`create_schedule`	Makes a schedule. Needs `name` and `commands`; takes `enabled`, `repeat`, `time`, `days`, `cron`, `timeZoneId`, `group` and `tags`.	Create schedules
`update_schedule`	Changes a schedule. Needs `id`, and takes only the fields to change; the rest stay as they are. It can't change what the schedule sends: to do that, delete it and make a new one.	Change schedules
`delete_schedule`	Deletes a schedule. Needs `id`. This can't be undone.	Delete schedules
`list_connectors`	Lists every connection with its status, worst first, and the processors they run on.	See the status of connections

Some tool names, such as get_room_state and set_room_command, come from an older word for a location. The tools take a location's id.

The schedule tools also need a Manager Licence. Under a User App Licence alone they answer that schedules need a Manager Licence. See Licences and limits.

Each tool describes its arguments to the assistant, so you rarely need to know them. A command is the same one the processor's own pages send: set_room_command returns whether it was accepted and queued for a connection. A queued command hasn't reached the location yet.

When a tool can't do something

A tool that can't do what it was asked answers normally, with isError set to true and a sentence the assistant can act on:

The assistant is told	Why
"This key may not use set_room_command: it needs the permission Locations or LocationCommands: Update. Keys made with the preset ReadAndControl have it."	The key lacks the permission. Make a key with Read and control, or tick Send commands to locations.
"This processor has no Manager Licence. Add one on the licence page to use locations and schedules."	A schedule tool on a processor with no Manager Licence.
"There is no location with the id … list_locations gives the ids of the locations."	The id isn't one of the processor's locations.
"Unknown argument 'wrong'. This tool takes: locationId."	The call used an argument the tool doesn't have.

The assistant corrects itself from these and tries again.

A request that isn't a valid call at all is a protocol error. A missing tool name, an unknown tool or arguments that aren't an object answer -32602; an unknown method answers -32601 — both with 200. Unreadable JSON answers -32700, and anything that isn't a single JSON-RPC request, such as a batch, answers -32600 — both with 400.

Try it with curl

curl --cacert box-ca.crt "https://192.168.10.22:8443/mcp" \
  -H "X-Api-Key: $CENTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A tools/call names the tool and gives its arguments:

curl --cacert box-ca.crt "https://192.168.10.22:8443/mcp" \
  -H "X-Api-Key: $CENTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_locations","arguments":{}}}'

The answer carries the result both as text and as structuredContent:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\"locations\":[{\"id\":\"823c7cc2-7a3b-4131-8524-ea452b6b815d\",\"name\":\"Room 101\", …" }
    ],
    "structuredContent": {
      "locations": [
        {
          "id": "823c7cc2-7a3b-4131-8524-ea452b6b815d",
          "name": "Room 101",
          "tags": ["suite"],
          "group": "Floor 1",
          "supportsGrms": true,
          "connectors": 1
        }
      ],
      "total": 1,
      "returned": 1
    },
    "isError": false
  }
}

Troubleshooting

You see	What it means	What to do
A certificate error, "self-signed certificate" or "unable to verify"	The computer doesn't trust the processor's certificate.	Trust the certificate, or set `NODE_EXTRA_CA_CERTS`.
401	No key, a key the processor doesn't know, a revoked or expired key, or a route that doesn't take keys.	Check the `X-Api-Key` header. Check the key on Settings → Access → API keys: make a new one if it was revoked, or give an expired one a later expiry.
400 with "Use HTTPS. Keys are not taken over plain HTTP."	The request went to the plain HTTP port, the User App port or the connection port.	Use `https://` and the admin HTTPS port. If a key was sent that way, revoke it.
403 on the request	The key is for another API.	Make a key for API and MCP.
423, feature `api`	The processor has no API Licence, or has neither a Manager Licence nor a User App Licence.	Add the licence on the Licence page.
423, feature `rooms`	A schedule tool with no Manager Licence, or a schedule change or a command while the Manager Licence is in its read-only days. A command still works if the processor has a User App Licence.	Add a Manager Licence.
429	Too many requests with one key, or too many requests with a key the processor doesn't know.	Wait the number of seconds in `Retry-After`.
413	The request is over 256 KB.	Send less in one call.
The assistant says it can't reach the server	The assistant runs somewhere that can't reach the site network, or the address or port is wrong.	Run it on a computer on the site network and check the address.
Some tools are refused	The key lacks their permission.	See When a tool can't do something.

What you need​

The endpoint​

Trust the processor's certificate​

Connect a desktop client​

Tools​

When a tool can't do something​

Try it with curl​

Troubleshooting​