API keys and MCP access
API keys and MCP access
MaxSuite already serves its tools over MCP, the protocol AI clients such as Claude Code and Claude use to call tools. To let an outside agent work on your workspace you either give it an API key, or connect it by signing in, and in both cases you keep its reach narrow.
Tool names
Every module's tools are named after the module.
- Inside MaxSuite, and on module pages, a tool is written
<module>.<verb>:costs.list,domains.expiring,tasks.create. - Over MCP the same tool is
<module>__<verb>:costs__list,domains__expiring,tasks__create.
The core's own tools use the module id core, for example core.listNotifications, which is core__listNotifications over MCP.
API keys
An API key is a password for a program. It never belongs to a person's session and never has administrator rights.
Make a key for one task
- Open the account menu, choose Account, and find API keys. Making and revoking keys needs
api-keys:manage. - Under New key, name it for the job it does, for example "link shops to the books".
- Set Expires in days. Left empty, it lives until someone revokes it.
- Tick Read-only if it only needs to look.
- Under What it may do, tick only the permissions it needs. Add
mcp:read, the permission on the MCP address itself; without it the key cannot reach MCP at all. - Optionally, under Modules it may reach, tick the modules it may call tools in. Tick nothing and its permissions are the only limit.
- Press Create key and copy it. Only a hash is stored, so it cannot be shown again.
Read-only, everything and Everything are shortcuts. The second is the easy mistake: one key holding everything turns every new tool into reach somebody has already granted. Start from the task instead.
What narrows a key
| What it does | |
|---|---|
| Permissions | Which acts it may ever perform. Never more than its maker holds: anything else is dropped, and the screen says how many were granted |
| Modules it may reach | Which modules' tools it may call at all, whatever its permissions. "Core / kernel" covers the core's own tools |
| Read-only | Tools that write are refused, even where a permission would allow them |
| Expires | It stops working on that day |
Two more settings are on the form:
- Acts as you: the key sees what you see, within its own permissions, including your own costs, runs and conversations. Without it, a key sees no rows wherever a module narrows rows to the people they belong to, because nobody is behind it. An empty answer from such a tool means that, not an empty workspace. A key that acts as you narrows when your permissions do and stops if your account is suspended. It is for your own assistant, not a shared integration, and it is fixed once made.
- Tool listing: All tools lists every tool the key may call. Search only lists four tools that find, describe and run the rest (
tools__search,tools__describe,tools__call_readandtools__call), for a client with little room in its context. The key can call the same tools either way.
Change or end a key
- Edit changes its name, permissions, modules, read-only flag and tool listing. Whatever holds the key gets the change on its next request.
- Revoke ends it at once: the next request is refused.
- A key also ends when it expires, and when the person who made it is suspended or removed.
- Revoking or narrowing a key is refused if the key is the last thing in the workspace able to grant some permission. The screen names it, and you can accept the loss and go ahead.
Every change a key makes is recorded in the audit trail with the key's name, so "what has this key been doing" has an answer.
Connect an MCP client with a key
claude mcp add --transport http max https://<your-deployment>/api/mcp \
--header "Authorization: Bearer max_…"
Replace max_… with your key. Each request stands on its own key, so revoking takes effect on the very next call. Opening https://<your-deployment>/api/mcp in a browser shows a page a person can read.
Connect an app by signing in
Apps that support sign-in for MCP, such as Claude's custom connectors, can connect without anyone copying a key. This is the MCP sign-in module, shown as Connections → Connected apps.
- An administrator turns on Sign-in for outside apps. Until then nobody can connect one. Turning it off later disconnects every app.
- In the app, add a custom connector with the address
https://<your-deployment>/api/mcp. - The app sends you to MaxSuite. Sign in if asked, read what is asking, and approve it.
- It appears under Your connected apps.
A connected app acts as the person who connected it, with their permissions, through the MCP tools this workspace offers. Its reach is fixed when it connects: if you are given more permissions later, connect it again to pass them on. Losing a permission applies at once.
Each connection can switch between List all tools and Search only, and can be disconnected. An administrator also sees Everyone in this workspace and can disconnect anyone's app. The key behind a connection shows on the API keys list as "Connected app" and is managed here, not there. See Connected apps.
What the client can call
Not what the client asks for. Each call is checked on the server:
- the tool list is filtered by the key's permissions, its modules, its read-only flag, what the deployment has installed and switched on, and what your workspace may use;
- a call to any tool that was not listed is refused, so guessing a name gets nothing. A tool from a module your workspace does not have answers
No tool "…".
Which modules MCP clients may reach at all is a workspace setting held by the MCP module, behind mcp:write, at GET/PATCH /api/mcp/access. A module with no setting is reachable. A setting can switch a module off, cap it to reading, or switch off single tools. See MCP.
What a key does not give you
- A sandbox. A key runs with its permissions, and only the approval rules stand between it and the act.
- Freedom from the approval check. Every tool call a key makes passes the approval rules and their defaults, so by default its writes ask a person and its spending always does. Only the forced asking for sensitive modules is skipped for keys, because a key is a caller somebody set up and answers for. See Agents and approvals.
- Named secrets. A key can see which secrets exist with
secrets:read, but it can never enter one, even holdingsecrets:manage. See Named secrets. - Granting access. Sharing a document, outline or folder, or approving an access request, is refused through any key.