Tokens & scopes

Every MCP call (and every direct REST call) carries a per-user API token. Tokens have scopes, can be restricted to specific companies and projects, and can be revoked instantly.

Token shape

Tokens are created in the web app under Company settings › MCP tokens › Create token. Pick a label, choose scopes, and optionally restrict to specific companies or projects. The token string is shown once at creation time and cannot be retrieved later, so save it immediately.

Label claude-code on my-laptop Human-readable name. Shows up on every comment and edit the token makes.

Scopes mcp.read mcp.comments mcp.tickets.write mcp.tickets.assign Granular. Read-only audit tokens want just mcp.read. Choose mutation scopes as needed. Jira sending requires a separate explicit mcp.jira.send grant.

Company filter All companies (no filter) Restrict to one company id to scope down a token.

Project filter All projects in those companies Restrict further to specific projects.

Tokens begin with vd_live_ or vd_test_. Treat them like passwords. Revoke at any time from the same settings page; revocation is effective immediately.

Scope matrix

Scope	What it grants	What it does not grant
mcp.read	Read accessible companies, projects, tickets, comments, capture assets, DevTools, frames, and report evidence.	No writes. Workspace report entitlements still apply.
mcp.comments	Post comments.	No ticket edits or assignment changes.
mcp.tickets.write	Create, edit, move, archive, restore, record branches and fixes, and unlink Jira issues.	Does not grant Jira sending or assignment changes.
mcp.tickets.assign	Add or remove ticket assignees.	No other ticket edits.
mcp.jira.send	Send tickets to the mapped Jira project. Explicitly opted in.	No connection or mapping administration; still needs an eligible workspace plan.

Read access accompanies every grant. Mutation permissions are independent: one does not automatically grant comments, assignment, or other mutation permissions. mark_duplicate and request_info additionally need comments permission.

The default full-access grant includes read, comments, ticket writes, and assignment. Jira sending is off unless explicitly selected, even in full access. Choose only read for an audit agent. Existing tokens may need their grants updated and the client reconnected before new tools can be used.

Restricting a token

When you create a token you can pin it to:

• One company (or several, by creating one token per company).
• Specific projects within those companies.

A token restricted to company co_abc123 and project proj_xyz789 will see only that project. List operations return only matching rows; writes against other rows return forbidden.

This is the right pattern for:

• Skills that should only touch one project.
• Tokens you embed in CI or agents you do not fully trust.
• Per-customer tokens if you are running Toado as a managed service for clients.

Per-skill tokens

If you run multiple skills (one for triage, one for verification, one for screenshot regression sweeps), give each its own token with the narrowest scope it needs. The token label appears on every comment, so per-skill tokens make audit trails self-explanatory.

Authentication header

For direct REST calls (not via MCP), pass the token as a Bearer:

curl https://api.toado.dev/api/v1/me \
  -H "Authorization: Bearer vd_live_example"

The MCP server handles this for you when you set TOADO_API_TOKEN in the env.

Rotating tokens

Two safe patterns:

Side-by-side rotation (recommended). Create a new token with the same scopes, update your config to use it, restart your client, then delete the old token. Zero downtime.

Cut-over rotation. Delete the old token, create a new one, update your config. Fastest, but every in-flight call from the old token is rejected immediately. Fine for one-off agent contexts.

Revocation is effective immediately. The next request with a revoked token returns 401 unauthorized.

Rate limits

Limit	Default	Configurable per company
Reads	600 / min / token	Yes
Writes	60 / min / token	Yes

429 responses include a retry_after header (seconds). The MCP server’s bulk tools (bulk_move_tickets, bulk_assign_tickets) call sequentially to stay inside the write budget, capping at 50 tickets per call.

Storage and exposure

• Tokens are hashed at rest. The plaintext is shown once at creation; we cannot recover it.
• Treat tokens like passwords: do not commit to version control, do not paste into shared chat threads.
• For local development, use a .env file ignored by git.
• For production, store in your platform’s secret manager (Vercel env vars, GitHub Actions secrets, etc.).

Comparing identities

Every write operation records the token’s owner and the token label. In the UI, comments and edits from MCP clients show:

Jason (claude-code on macbook) · via MCP · just now

That makes it easy to tell which agent or human did what, even when one user has several tokens.

Where to next

• Tools reference for the full surface and what each tool needs.
• API tokens (user view) for the same topic framed for end users.
• Security for the broader trust model.