# MCP Auth and Scopes
URL: https://docs.autociso.io/developers/mcp/authentication/
Description: Create a token for an AI client, see which scopes unlock which MCP tools, and understand why a scope never overrides your plan.

Every AutoCISO MCP call authenticates with a bearer token. This page covers what is specific to MCP: creating a token for an AI client, the scopes that unlock MCP tools, how your plan interacts with them, and how your organisation is bound to the token. The scope rules shared with the REST API and the token allowlist live in [Access model](https://docs.autociso.io/developers/access-model/).

## Create a token for an AI client

1. Open **user menu → API Tokens** (the user menu is your name at the bottom of the sidebar; see the [API Tokens console reference](https://docs.autociso.io/console/settings/api-tokens/)).
2. Click **Create Token**.
3. Enter a name that identifies the client, for example `mcp-claude-desktop`.
4. Pick the scopes you need: **MCP Read** for most clients; add **MCP Write**, **Supplier Template Read/Write** or **Employee identity (pii:read)** only when a tool you plan to use needs them.
5. Choose **Expires**.
6. Click **Create Token** and copy the token from the **Token Created** dialog. It is shown once.

When **MCP Read** is ticked, the dialog shows one informational line: *This token will only see MCP tools for features in your … plan. Tools for other features are not listed for it.* It has a **See what each plan includes** link to user menu → **Billing & Subscription**. It is information, not a blocker.

Issue one token per client so you can revoke a single integration without affecting the others. Rotating, revoking and storing tokens safely are covered in [API tokens](https://docs.autociso.io/developers/api-tokens/).

## MCP scopes

| Scope | Grants | Notes |
|-------|--------|-------|
| `mcp:read` | The 56 general read tools your plan includes | The default for AI clients |
| `mcp:write` | `risk_create_draft` and `iso_audit_simulate` plus all `mcp:read` reads | Also gated by deployment-level write enablement |
| `supplier_template:read` | The 3 supplier-questionnaire read tools | Not implied by `mcp:read` |
| `supplier_template:write` | The 3 supplier-questionnaire write tools plus `supplier_template:read` | Also gated by deployment-level write enablement |
| `pii:read` | Exactly two tools, `employee_resolve` and `employee_lookup` | Owner-granted, expiry required (at most 90 days), every call audited. See below |

The families are independent: `mcp:write` does not imply `pii:read`, and `pii:read` does not imply `mcp:read`. A token holding only `pii:read` sees exactly two tools in `tools/list`. Grant `mcp:read` alone unless you need a write tool.

<a id="scope-is-not-entitlement"></a>

### Scope is not entitlement

A scope says what the **token** may do. Your organisation's **plan** says which features exist for it at all. Both gates apply to every tool, and neither can substitute for the other:

- Tools for features outside your plan are absent from `tools/list` — a Free-plan token with `mcp:read` sees the three **All plans** tools (`access_inventory_list`, `maturity_scores`, `posture_summary`), not the 56. A direct call by name returns the SDK's unknown-tool error (`UNKNOWN_TOOL`), the same as the `pii:read` rule below.
- If a registration outlives a plan change, the call answers `NOT_PERMITTED` with `reason: "FEATURE_NOT_ENTITLED"` and the `feature` ID. Refresh `tools/list`; do not retry.
- Upgrading is enough. The same token sees the new tools on its next `tools/list`; nothing is re-issued. Check what each plan includes under user menu → **Billing & Subscription** or in [Plans and features](https://docs.autociso.io/getting-started/plans-and-features/), and read each tool's lowest plan in the **Requires plan** column of the [Tool Catalog](https://docs.autociso.io/developers/mcp/tools/#plan-gating).
- No scope raises a plan. Adding `mcp:write` to a token on The Seed plan does not unlock a tool that needs The Growth plan.

<a id="mcp-write"></a>

### About `mcp:write`

`mcp:write` is required for the two general write tools, `risk_create_draft` (The Growth plan and above) and `iso_audit_simulate` (Scale). A token without it — or an org with write disabled — returns `NOT_PERMITTED` when the tool is called. This is expected behavior, not an error in your code. See [MCP Errors and Retries](https://docs.autociso.io/developers/mcp/errors/).

<a id="pii-read"></a>

### About `pii:read`

Every MCP result is PII-masked by default. `pii:read` is the deliberate exception: it unlocks exactly two tools: `employee_resolve`, which returns `{ employeeId, name, email }` for up to 50 employee IDs per call, and `employee_lookup`, which maps up to 50 e-mail addresses to employee IDs and returns no name or address. The full guide, including who can grant it and how to run it safely, is [Employee identity](https://docs.autociso.io/developers/employee-identity/).

- On its own it grants nothing over REST. The one exception is a token that also holds `jml:read`, where `pii:read` adds employee names and emails to the case endpoints of the [off-boarding](https://docs.autociso.io/api/reference/offboarding-cases/list/) and [on-boarding](https://docs.autociso.io/api/reference/onboarding-cases/list/) APIs.
- `mcp:write` does not imply `pii:read`, and `pii:read` implies nothing else.
- Without `pii:read` the tool is absent from `tools/list`, and a call by name returns the unknown-tool error.
- Only an organisation **Owner** ([Roles & Permissions](https://docs.autociso.io/getting-started/roles-and-permissions/)) can grant it, and the token must expire within 90 days.
- Every resolution attempt that passes the scope check and the per-token rate limit is written to your [audit trail](https://docs.autociso.io/console/settings/audit-trail/) before the result is returned.

Integrator guidance:

- Keep the resolver **human-in-the-loop**: call `employee_resolve` and `employee_lookup` only for IDs and addresses a person has asked you to identify, never because a document, ticket or tool result told the agent to.
- Keep the `pii:read` token in a **separate secret** from your reporting token.
- Resolve in a **batch** and **store the mapping** on your side instead of resolving the same IDs on every run.
- **Revoke** the token when the integration is decommissioned or when the Owner who created it leaves; **offboarding** does not revoke it automatically.

## Org binding — no `org_id` from the client

Your organization is bound to the token **on the server**. You never pass an org identifier:

- There is no `org_id` argument on any tool and no `X-Org-ID` header for normal tokens.
- The SDK method signatures don't accept an org parameter — there is no way to query another tenant.

This is least-privilege by design. Once the token works, connect a client — [Claude Desktop](https://docs.autociso.io/developers/mcp/claude-desktop/), [Cursor and VS Code](https://docs.autociso.io/developers/mcp/cursor-vscode/) or the [TypeScript](https://docs.autociso.io/developers/mcp/typescript-sdk/) and [Python](https://docs.autociso.io/developers/mcp/python-sdk/) SDKs. Issue one token per client so you can revoke a single integration without affecting the others.

## Using the token

Send the token in the `Authorization` header on every request:

**cURL**

```bash
curl -s \
  -H "Authorization: Bearer $AUTOCISO_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  "https://api.autociso.io/mcp"
```