Employee identity over MCP (pii:read)

Employee identity over MCP (pii:read)

Plans: every plan (the Audit Trail page needs a plan that includes it; the entries are readable over MCP with audit_trail_search on every plan). Where: user menu → API Tokens; the /mcp endpoint

MCP results have always masked employee names and emails and returned the opaque employeeId as a join key. Integrations that need to act on a finding — email a manager, open a ticket for a person — had no sanctioned way to turn that ID back into a name. Now they do, on an opt-in credential that an Owner grants deliberately.

What’s new

A new scope: Employee identity (pii:read)

In user menu → API Tokens → Create Token, an organisation Owner can now select Employee identity (pii:read). The dialog shows a warning, requires an expiry of at most 90 days (Never and 1 year are disabled; 90 days is preselected) and asks you to confirm Grant employee identity access? before the token is created. Tokens carrying the scope show a PII tag in the list. A Manager can still create every other kind of token, and can still revoke a pii:read token.

One new tool: employee_resolve

A token with pii:read sees one extra tool, employee_resolve(employeeIds[]), which returns { employeeId, name, email } for up to 50 IDs per call and lists unknown IDs explicitly. It is rate-limited per token, exists only for tokens with the scope (for everyone else it is unregistered, not merely hidden), and every call is written to your audit trail — the token and the IDs requested, never the names — before the result is returned. Everything else on MCP is exactly as masked as before. See About pii:read and the guide.

Token creation and revocation are on the audit trail

Every API token creation and revocation — any scope — now writes an api_token.created / api_token.revoked entry (HIGH for pii:read, MEDIUM otherwise) to the hash-chained audit trail, so a grant and its use sit in the same ledger.

Expiry rotation cues

The token list now shows Expires in N days once a token is within 14 days of expiry. supplier_template:write tokens, which already required an expiry, no longer offer Never in the dialog.

Rollout

The scope is enabled per deployment. Where it is not yet enabled, the option is shown disabled in the console and the API answers 422 SCOPE_UNAVAILABLE; nothing can be minted by accident. If it is switched off later, existing pii:read tokens stay valid but the tool disappears and no new grants are possible.

For SDK users

Both SDKs learned the tool-plane RATE_LIMITED code: a non-retryable ToolError carrying retryAfterSeconds (retry_after_seconds in Python). The SDK does not retry it for you. See MCP Errors and Retries.