Connecting an AI agent to the MCP server

An external AI client — your own chatbot, a voice platform, or an assistant such as Claude or ChatGPT with MCP support — talks to the environment through an endpoint that speaks JSON-RPC 2.0. There is no longer one such endpoint, but three. Which one you need is the first decision you make, because a key opens exactly one of them.

The three doors

All three speak the same protocol and share the same transport layer. They differ in what lies behind them, and therefore in how much trust they ask for.

The names mean exactly what they say: config is administration — setting things that then apply to everyone — and operations is execution. Assigning a table is operations; deciding which tables exist is config.

One key opens one door

An AI agent authenticates with a user key of the form sk_<license>_<user>_<secret>. You choose the scope when you create it, and that decides which door the key opens. A booking key on /mcpconfig gets a 401 — and it gets it before the login, so a key for the wrong door never obtains a session.

Two things about this regularly surprise people:

• An empty scope means booking. Keys that predate the split were not silently narrowed — that would have broken working integrations — so the booking door accepts both booking and empty.
• The REST API is part of the booking family. The same scope is checked on REST v1 and v2. A key refused on /mcp therefore does not get in through REST either.

You manage keys under Configuration › System › API, which requires the right menu_config_api. The full key is shown once and stored hashed afterwards — save it immediately. A key can also be given an expiry date and can be revoked rather than deleted, so that afterwards it is still possible to see what it was. See How does an API key work?.

Besides a key, a client can also connect through OAuth: the user then logs in on the environment and approves the client in the browser. From the door onwards there is no difference — both name one user of one license, with the same rights and the same audit trail.

What an agent may do: three layers

Getting in is not the same as being allowed to do something. Behind every door the same chain is checked per tool, and it is an AND:

1. The master right of the door — tool_use, tool_config_use or tool_operations_use. One switch that turns the whole door on or off.
2. The right on that one tool — for example tool_config_object_update_apply. Plan and apply are separate rights, so you can let somebody see what a change would do without letting them make it.
3. The domain right — the same right the screen uses that performs the same act. No separate per-endpoint rights are added: somebody who may not edit a customer in the screens cannot do it through a tool either.

The rights sit in their own group per door: MCP, MCP-Config and MCP-Operations. See AI tool rights.

Public tools exist only on the booking door — tools a website visitor can reach without a logged-in user. On the configuration and operations doors nothing is public and every call without a login is refused, reads included.

Levels: the same number, three meanings

Every tool carries a level. That number means something different per door, and deliberately so — each time it describes the protection that belongs to that door.

The configuration door additionally has something the other two do not: two locks that must both be open before anything is written at all. One is set by the supplier for the whole environment, the other by the license holder. If either is closed, every write is refused — and so is every read, because otherwise the door you cannot open would still describe in full detail what is behind it.

Connecting in five steps

1. Switch the agent on

Without an active agent nothing happens, in any channel. Under Configuration › AI › Agent settings you switch on Agent active. That is also where you choose the Agent mode: reservations or events. That choice decides which tools the booking door offers, so make it deliberately — switching on both leads to wrong tool choices. See Agent settings.

2. Create a key with the right scope

Choose the scope belonging to the door from the table above. If you want a client that both books and configures, that is two keys — and that is exactly the intention, because they are two levels of trust.

3. Connect your client

The endpoint is the address of your own environment with the path appended:

https://your-environment.example.com/mcp
https://your-environment.example.com/mcpconfig
https://your-environment.example.com/mcpoperations

How you enter that URL differs per client, and that is where it gets stuck in practice: many clients have no field for a header at all. There are three routes, and the first one is the right one for most people.

Route 1: log in through the browser, without a key

A client such as Claude Desktop only asks for a URL when you add your own connector — under Advanced settings there is at most an optional OAuth Client ID and Secret, and nowhere a free header field. Nor does it need one: the environment publishes the standard OAuth documents and registers the client itself. You paste the URL, a browser window opens, you log in with your own account and see on a consent screen what the client is asking for. After that it is connected.

No key is involved in this route. So there is nothing to store, to share or to lose. The rights are those of your account, and the door follows from the URL you entered.

Two things to know beforehand:

• The client connects from the provider's infrastructure, not from your computer. The environment must therefore be reachable from the internet. A local test environment, or one behind an IP filter, does not work this way.
• A support account cannot do this. Such an account has no license of its own but becomes one each time; a token does the opposite and pins one user down for days. The consent screen therefore refuses, and points you to the screen where you first switch to the user this connection belongs to.

Route 2: a client that does understand headers

If your client can send a header, the key travels as Authorization: Bearer <key> or as X-API-KEY; if both are present, Authorization wins. On the Claude Code command line, for example:

claude mcp add --transport http ireserve-config \
  https://your-environment.example.com/mcpconfig \
  --header "Authorization: Bearer sk_..."

The key then ends up in the client's configuration on your own machine. That is exactly where it belongs: in a setting, not in a conversation.

Route 3: a client that only knows local servers

Some clients can only start a local program and cannot address a URL directly. In between you put a small bridge that passes the connection on and adds the header; mcp-remote is the common tool for this. In the client's configuration, put the command with the URL and the header after it, and keep the key in an environment variable rather than in the file itself. Pick a recent version — older ones contained a serious security flaw.

4. Check what you get back

You ask which tools are available with the standard MCP method tools/list; you run one with tools/call. That is the protocol, not something of ours — a client that speaks MCP handles this itself.

The list is not a fixed list. It depends on the door, on your rights, on the agent mode and on which parts have been configured. If a tool you expected is missing, that is almost always a right or a setting and not a fault. If you get an empty list while the key works, look at the master right of that door first.

5. Test without your client

Before you go digging in your own integration: the tool console under Configuration › AI › Tool console runs a single tool directly, through exactly the same path as the endpoint. You see the raw result and the matching line from the audit trail. If it works there and not for you, the problem is in your connection or your key. See Using the tool console.

Note: writing tools do real things there. A test booking is a real booking.

When it goes wrong

Every refused call writes a line to the security log, with the reason and with which door it concerned. The answer contains a reference to that line, so a report of "it says unauthorized" leads straight to its own log entry. The most common causes, in order: the header does not arrive, the license-wide API key was used instead of a user key, or the key was made for a different door.

The widget is something else

The built-in chat widget has no logged-in user and therefore runs on a fixed list of visitor tools on the booking door. It needs no scoped key — see Adding the AI Widget to your website.