What MCP is
What the Model Context Protocol lets a client do against a workspace here.
The Model Context Protocol lets an AI client call tools in another system. This
product exposes a fixed set of named tools at one endpoint, /mcp, so a client
such as Claude, ChatGPT or Gemini can read and work the helpdesk queue on your
behalf.
Those tools, and nothing else. The rest of the product is not reachable this way. See Limits for what that rules out.
The tools
The complete, current list, with each tool's role floor, is in the helpdesk under Settings → MCP. It is generated from the running server, so it is always the list your deployment actually serves. The pages below describe the tools by what they help you get done.
Each tool applies the same role floor as the equivalent HTTP route, using the same guard.
The core ticket and knowledge-base tools each have their own page:
| Tool | What it does | Role needed |
|---|---|---|
list_tickets | Filter and page the ticket queue | viewer |
get_ticket | Read one ticket with its message timeline | viewer |
create_ticket | Open a new ticket | editor |
reply_to_ticket | Post a customer reply or an internal note | editor |
search_knowledge_base | Semantic search over the workspace knowledge bases | viewer |
Every other tool is on one page with the tools it works alongside:
| Page | What you can get done |
|---|---|
| Workspaces and people | See your workspaces, members and teams; invite a teammate |
| Working a ticket | Update, snooze, reopen, merge, split and link tickets; read a ticket's summary |
| To-dos and time | Keep a ticket's checklist and log time on it |
| Customers and companies | Find, read, add and correct customers; look up companies |
| Macros and canned replies | Use and create macros and approved reply snippets |
| Attachments and sharing | Read a ticket's images and text files; share a ticket to Slack or Teams |
| Custom fields, saved views and insights | Set custom fields, open saved views, read queue figures and SLA targets |
| Conversations and AI actions | Read AI call and chat transcripts, see the live queue, decide proposed actions |
| Help centre | Search, draft and edit help-centre articles and collections |
| Integrations | See what is connected and what could be |
| e-automate lookups | Read a dealer's e-automate accounts, machines, contracts, meters and orders |
| e-automate filing | Raise service calls, supply orders and meter readings in e-automate |
Each page gives every tool's role floor and whether it changes data.
Source: _TOOLS in services/runtime/src/runtime/mcp/tools.py, and the
require_read / require_write / require_admin call inside each handler.
Symbol names rather than line numbers on purpose: line numbers in this section
went stale once already, and a stale number reads as a checked one.
Every call acts inside one workspace
A connection authenticates once. A workspace is chosen per call, not per connection, because one account can belong to several workspaces.
Each tool takes an optional workspace_id. If you belong to exactly one
workspace you can leave it out and the server uses that one. If you belong to
several and name none, the call is refused and you are asked to name one. If you
name a workspace you are not a member of, you get the same answer as naming one
that does not exist.
Source: resolve_tenant in services/runtime/src/runtime/mcp/tools.py and
services/runtime/src/runtime/auth/workspaces.py.
It is the same product, not a copy of it
Each tool is a thin wrapper. It works out which workspace the call acts in, applies the same role check the equivalent HTTP route applies, binds the identity the database reads for row level security, and then calls the very same function the REST API calls. No query is written twice, so no rule can be enforced in one place and forgotten in the other.
Source: the module docstring and the handlers in
services/runtime/src/runtime/mcp/tools.py.
Connecting a client
- Connect Claude — claude.ai, Claude Desktop, Claude Code
- Connect ChatGPT — developer-mode connector
- Connect Gemini — the Gemini app and the Gemini CLI
The same URL works for all of them; only where you paste it differs.
What is off by default
MCP is off unless an operator turns it on. A deployment that never opted in has
no /mcp route at all.
Source: Settings.mcp_enabled in services/runtime/src/runtime/config.py and
the conditional route registration in services/runtime/src/runtime/main.py.
The connection URL belongs to the deployment
There is no single address for this product. Each deployment publishes its own,
built from MCP_PUBLIC_BASE_URL rather than from the request, and a deployment
with MCP switched off publishes none at all.
Two places answer it, and they answer from the same configuration: Settings →
MCP in the helpdesk, and GET /v1/mcp/availability, which 404s when the
deployment does not serve /mcp. The app store's Claude, ChatGPT and Gemini
entries read the same route and refuse to print a URL when it is off.
Anywhere in these pages that a host is written as <MCP-HOST-PLACEHOLDER>, that
is the value to substitute.
How these pages are kept honest
The MCP surface is invisible to the generated API reference, by construction:
/mcp is registered as a plain route rather than a documented one
(services/runtime/src/runtime/mcp/asgi.py), and the two discovery routes are
excluded from the schema (services/runtime/src/runtime/mcp/well_known.py).
Nothing generates these pages and nothing will catch them going stale.
So every behavioural statement in this section names the file it came from.
Review trigger: any change under services/runtime/src/runtime/mcp/ requires
these pages to be re-checked against source in the same change. It is a human
gate, and it is weaker than the check that protects the REST reference — it has
already failed once, when the tool list grew and this page kept stating the old
count for months. That is why it no longer states one.