MCP Auth and Scopes

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.

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).
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.

MCP scopes

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.

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, and read each tool’s lowest plan in the Requires plan column of the Tool Catalog.
• 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.

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.

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.

• 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 and on-boarding 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) 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 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, Cursor and VS Code or the TypeScript and Python 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 -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"