13.1How the MCP server works

The endpoint

The MCP server is part of the API. With the default installation, where the API is published under /backend, its address is:

https://gateway.example.com/backend/mcp

This is the address you give an MCP client.

Licence

The MCP server needs the MCP Tools module (mcp) on your licence. On an instance without it:

• Every tool call is refused, and a new session is offered no tools at all.
• The MCP Tools screen is hidden.
• The MCP Settings screen stays available, so that agent sign-in can always be switched off, even after a licence lapses.

See Chapter 19, Licence, updates and backups.

Two ways to authenticate

An agent always acts as a person. It can prove that in one of two ways:

With OAuth, the person signs in through the browser and approves the connection; no secret is copied anywhere. With an API key, you create the key yourself (see Chapter 12, API keys) and put it in the client's configuration.

The MCP endpoint never accepts a browser session or a console sign-in token. An agent token, in turn, works only on /mcp — it is refused on the rest of the API. Because of this separation, an agent can never reach the console's approval routes, so it can never approve its own operations.

What an agent is allowed to do

An agent can never do more than its person. Its effective permissions are:

• the role chosen for it (on the consent screen, or the API key's role), intersected with what the person holds right now;
• narrowed to read-only if the person chose read-only access;
• limited to one directory.

Every tool checks its own permission before it runs; for example, SearchAdUsers needs ad:users:list and GetAdUser needs ad:users:read. A refused call returns a short "access denied" message to the agent. Every operation an agent performs is recorded in the operations log under its person's name, with Via agent and the agent's name beside it (see Chapter 9, Operations log, approvals and waiting operations).