MCP Tool Permissions

The third permission axis. Table scopes say what data a credential may touch; tool permissions say which operations it may perform at all.

You set them on the Tools tab of an API key or an AI connector.

Why this axis exists separately

An MCP connector is not a query client. It can create tables, publish apps, run automations, send mail, mint API keys — operations that have nothing to do with reading a row, and that a table scope has no way to describe.

Scoping those by data would be the wrong shape. "May this connector create a role?" is not a question about any table. So the gateway asks it separately: a credential carries a list of tool groups it may use, and every tool belongs to exactly one.

The groups

A new key starts with `Data` only. Everything else is off until you turn it on — so a fresh credential can read and write rows and nothing more.

Levels are built from verbs

A level is a combination of three verbs, and a tool declares which one it needs:

A tool is allowed when its group's level contains the verb the tool requires. list_tables needs read; create_table needs write; delete_table needs delete.

That is why ReadWrite on Schema lets a connector add a column but not drop one — the difference is a verb, not a separate setting.

Per-tool overrides

Groups are the coarse control. When a group is nearly right but not exactly, add an override for a single tool:

Two shapes cover almost every real case:

One tool out of a group you granted. Automations at Full, Deny on the one automation tool that talks to a payment provider.

One tool out of a group you did not grant. Security at None, Allow on list_api_keys so a monitoring integration can check for expiring keys — without giving it the ability to mint one.

That second shape is the one worth remembering. It replaces the usual bad trade of granting a whole group for the sake of one tool.

Presets

The Tools tab offers one-click starting points. They replace the entire state, overrides included — a preset is a fresh start, not a merge.

Worth knowing what "read only" means here: it grants Read on every group except `Security`, which is set to `None`. Listing API keys is technically a read, but it is not the kind of read somebody asking for a read-only key has in mind.

Treat a preset as a starting point you then narrow, not as a finished configuration.

The rule that surprises people

A tool permission is not a data permission. Granting the Data group does not grant a single table. Granting Docs does not grant a single document.

The two are checked independently and both must pass:

  MCP call arrives
      |
      +-- is this tool's group allowed at the verb it needs?   -> no: refused here
      |
      +-- do the table / doc scopes allow this specific target? -> no: refused here
      |
      v
   executed

This composes in exactly one direction: each axis can only narrow. There is no setting on the tools axis that widens the data axis, and none on the data axis that enables a tool.

The practical consequence is that a connector with every tool group at Full and no table scopes can do nothing at all — it can call every tool, and every one of them will find nothing to act on. That is the correct starting position for a new connector: turn on the tools it needs, then grant the data, and watch what it does in the Logs tab before widening either.

Guidance

• Start from what the integration does, not from what it might do. Tool groups are one click to add later.

• Keep `Security` at `None` unless the integration's actual job is credential management. A key that can mint keys is a key that can outlive its own revocation.

• Prefer an override to a group. Needing one tool is a reason for one Allow, not for a whole group.

• Read the 403 carefully. "Tool not permitted" is this axis; SCOPE_VIOLATION is the data axis. They are fixed in different tabs.

Next

• Credentials and Principals — the three axes and how they compose.

• Docs Scopes — the document tree and its inheritance rules.