Auth & scopes

MCP uses the same scoped agx_ API key as the REST API, and the same scope model. One credential, one lock.

The key

• Sent as Authorization: Bearer agx_<key> on POST /v1/mcp (bare agx_… also accepted — see Connect).
• Issued per organization in Settings → API Keys. The key carries that org's tenant binding — it can never touch another org's data.
• Hash-only, shown once at creation. Rotate/revoke any time; the client is cut off instantly.

Scopes gate everything — default-deny

A key holds a set of scopes. No scope → no access at execution time. The split is:

1. Discovery (tools/list) is public — NOT scope-filtered. It returns the full static catalog (the same 135 tools for everyone, key or no key) so an agent can see what's possible. Authenticating adds your org's exposed workflow tools; it does not remove any static tool.
2. Execution (tools/call) is gated. Every call re-checks the required scope (and tenant + ACL) at operations.execute(). A tool you hold no scope for is refused when called — a read-only key can see create_contact in the list but gets a scope error if it tries to call it.

info

Think capabilities vs. authorization: the catalog advertises everything the server can do; your key's scopes decide what it's allowed to do. Discovery is public; execution is enforced.

Scope vocabulary

Scopes are coarse {resource}:{action}. write / author / run imply read on the same resource — you don't grant the read counterpart separately.

CRM (per entity: contacts, companies, deals, tasks, notes, activities)

Scope	Grants
<entity>:read	View and list; search tools, get_…, list_… associations
<entity>:write	Create / update / delete; link / unlink (implies read)

Association tools require the scope on both sides — e.g. link_contact_to_company needs contacts:write and companies:write.

Workflows

Scope	Grants
workflows:read	List nodes, read/list workflows, validate, read executions
workflows:author	Create, edit, import, activate/deactivate, delete (implies read)
workflows:run	Run and test workflows and single nodes (implies read)

author and run are deliberately separate, so a key can be "build but not run" or "run but not edit". Execution is additionally confirm-gated (human-in-the-loop) — see Recipes.

Knowledge Base

Scope	Grants
knowledge:read	List KBs, read documents, search and ask (RAG)
knowledge:write	Create/update/delete KBs and documents (implies read)

Analytics

Scope	Grants
analytics:read	List/read datasets, charts, dashboards; run queries/charts; NL→SQL; inspect schema
analytics:write	Create/update/delete datasets, charts, dashboards (implies read)

Mapping a tool to its scope

Every tool in the catalog lists its Required scope. Rule of thumb:

• search_… / get_… / list_… → …:read
• create_… / update_… / delete_… / link_… / run_… / edit_… → the resource's write / author / run

Least privilege

Grant the narrowest set that gets the job done. A reporting agent needs only …:read scopes; a data-entry agent adds the relevant …:write. This is the same posture the REST API enforces — the Scopes reference is shared between both surfaces.