# AI assistants (MCP)

Connect Maci to Claude, ChatGPT or another assistant that speaks the Model Context Protocol, and ask it about your refrigeration units in your own words. It reads through the API, so it sees what a key of yours would see, and it cannot change anything.

## What it is

Maci's MCP server is at `https://mcp.maci.energy/mcp`. An assistant connected to it can answer questions such as:

- Which of our units are due a leak check in November?
- Are there open alarms at the Vesterbro store, and has anyone taken them?
- When was MC-0482 last serviced, and what was done?
- How much R404A do we have in our cold rooms, in tonnes of CO2 equivalent?

The assistant calls the tools below, each one a GET of this API, and answers from what comes back. Nothing is written, created or deleted through it.

## Connecting an assistant

An admin of your organisation connects it once. In the assistant, add a custom connector (in Claude and ChatGPT it is under Settings, Connectors) with the address `https://mcp.maci.energy/mcp`. The assistant then sends you to Maci, where you log in as always, choose the organisation and say yes with your passkey.

Only an admin can connect an organisation, and a customer only once at least one unit has Maci Service, as with an API key. A refrigeration company needs none of its own: it reads the units it has a grant on.

Setup for Claude Code, Cursor, VS Code and other clients, example questions and skills (step-by-step tasks such as a leak check plan or an alarm report) are in [Maci-Intelligence/developers](https://github.com/Maci-Intelligence/developers) on GitHub, with webhook receivers and scripts for the API.

## Tools

The assistant sees only the tools of the scopes it was given. The answers are the API's own, with the fields of the [reference](https://api.maci.energy/docs/units.md).

| Tool | What it gives | Scope |
| --- | --- | --- |
| `list_sites` | The organisation's sites (stores, warehouses, kitchens) and the customers' sites it has units on through a grant. Each has an id, a name and an address. | `units:read` |
| `list_units` | The refrigeration units the organisation works with: its own, and customers' units it has a grant on. Each has its Maci-ID (MC-0482), name, site, refrigerant, charge and status. Filter by site, status or what changed since a time. | `units:read` |
| `get_unit` | One refrigeration unit's passport: its master data, nameplate, refrigerant, charge and CO2 equivalent, site and components. | `units:read` |
| `list_components` | The components of a unit: compressors, evaporators, condensers, controllers, valves and the rest, each with its type and fields. | `units:read` |
| `list_service_entries` | The service log of a unit: visits, repairs and checks, oldest first, each with its date, type and text. | `service:read` |
| `get_fgas_status` | Whether a unit's leak checks under the F-gas regulation are up to date: how often it must be checked, when it was last checked and when the next is due. Needs Maci Service on the unit. | `fgas:read` |
| `list_fgas_entries` | The F-log of a unit, the logbook the F-gas regulation asks for: leak checks, refrigerant added and recovered, repairs, oldest first. Entries are never changed: a correction is a new entry. Needs Maci Service on the unit. | `fgas:read` |
| `list_alarms` | Alarms from Maci Intelligence on the units the organisation owns or watches: what was wrong, on which unit, when it started and cleared, and who took it. Filter by open, unit or since a time. | `alarms:read` |
| `get_alarm` | One alarm from Maci Intelligence with its values, its state, who was told and who took and closed it. | `alarms:read` |
| `get_usage` | How many calls this connection and the organisation have made this month, and the month's limit. | any |

## What an assistant can reach

- Only reading: the scopes `units:read`, `service:read`, `fgas:read`, `alarms:read`. No tool changes anything in Maci, so nothing a note or a mail says can make the assistant act there.
- Only what your organisation may see in Maci, by the same rules as a key: your own units, and customers' units you have a grant on.
- Every tool call is a call to the API: it is logged, it counts towards the month's limit, and it is held to the limit a minute, under [API-nøgler](https://app.maci.energy/organization/api-keys).
- Your data goes to the assistant you chose, and from there to its provider. Connect only an assistant your organisation is allowed to use.

## Removing a connection

The connections are listed under [API-nøgler](https://app.maci.energy/organization/api-keys), **Forbundne AI-assistenter**, with who made each one and when it was last used. Removing one stops it at once. A connection that is not used for 30 days ends by itself.

## For developers: the OAuth flow

The server follows the MCP specification's authorization (2026-07-28). Clients that support it need nothing more than the address.

| Part | How |
| --- | --- |
| Protected resource metadata | `https://mcp.maci.energy/.well-known/oauth-protected-resource/mcp` (RFC 9728) |
| Authorization server | `https://app.maci.energy`, metadata at `https://app.maci.energy/.well-known/oauth-authorization-server` (RFC 8414) |
| Clients | A Client ID Metadata Document (an https `client_id`), or Dynamic Client Registration (RFC 7591) at `https://app.maci.energy/oauth/register`. Public clients only: `token_endpoint_auth_method` `none`. |
| Flow | Authorization code with PKCE, `S256` only. The redirect address must match exactly. Send `resource` with `https://mcp.maci.energy/mcp`: the token works there and nowhere else, not on `https://api.maci.energy/v1`. |
| Tokens | An access token (`maci_oauth_…`) lasts 60 minutes. A refresh token (`maci_refresh_…`) is used once and gives a new pair; one used again ends the connection. |
| Revocation | `https://app.maci.energy/oauth/revoke` (RFC 7009): a refresh token ends the connection. |