Workspace-scoped MCP tokens: give an agent one shared board, not your whole account

Create an extra MCP token from Account → Extra MCP tokens and pick a workspace from the dropdown, and that token can only read and write tasks on that one board — it calls a narrower set of tools, and anything outside its workspace comes back as "not found" rather than a permission error. It's the third narrowing axis on a Done token, next to read-only and single-project, and it exists specifically for the moment an account belongs to more than one workspace: without it, a token reaches every board the account can see, agent included.

Why isn't project-scoping enough once you share a workspace?

A project-scoped token was already the narrowest option, but a project lives inside exactly one workspace — it can't reach across boards, but it also can't cover "everything in this one shared workspace, whatever projects get added to it later." Once an account belongs to more than one workspace — a personal one plus one shared with each set of collaborators — an otherwise-unscoped token reaches all of them at once, because reading isn't an action you can gate per call. It's a property of scope, not of any single tool invocation, so it has to be enforced at the credential level instead.

How a workspace-scoped token is enforced

The same shape as project scoping: a default-deny allow-list (WORKSPACE_TOOLS in lib/mcp.ts) that a tool has to be explicitly added to before a workspace-scoped token can call it at all — never the reverse. project_id and workspace_id are mutually exclusive on the same token, refused together at creation, since a project-scoped token is already confined to that project's one workspace and pairing the two only invites a combination that could disagree.

What an agent can still do with a workspace-scoped token

• The full task lifecycle on that board: list_tasks, list_my_tasks, and next_task (their workspace filter forced to the token's own, so a caller can't widen it), get_task, update_task, comment_on_task, complete_task, propose_completion, claim_task, decline_task, release_task, and run tracking (start_run, end_run, check_budget).
• create_task — forced into the token's workspace, so it can't file a task into a project or parent that lives elsewhere.
• list_projects and list_workspaces — but filtered to just that one board; the names of the account's other workspaces never come back in the response.

What gets refused, not half-scoped

Anything that reads across the whole account without a workspace filter of its own — get_digest, search_activity, list_tags, list_goals, changes_since, list_triggers — is refused outright for a workspace-scoped token today, rather than shipped as a partial read that quietly spans every board. A tool added to Done later doesn't inherit access by default either: it's refused for a workspace-scoped token until somebody decides how it narrows, and a repo test (tests/scoped-tokens.test.ts) holds the allow-list exhaustive against its own enforcement so an unscoped addition fails the build instead of leaking quietly. The advertised tool list respects this too — a workspace-scoped client isn't even shown a tool it isn't allowed to call, rather than being shown it and refused at call time.

Does the scope cover the live event stream too?

Yes. /api/events accepts a bearer MCP token the same way /mcp does, so a scope that only covered tool calls would still hand a workspace-scoped credential every other board's task changes, comments, and agent requests over the stream — the same leak through a different door. The SSE connection enforces the identical workspace check.

Setting one up

From Account → Extra MCP tokens, the workspace picker only appears once the account actually belongs to more than one workspace — nothing to narrow to otherwise. Pick a workspace and it clears any project selection (they're mutually exclusive); the token is shown once at creation, the same as every other Done token, so copy it before navigating away.

Do I need a paid plan for this?

No — as shipped, creating a workspace-scoped token has no plan check anywhere in the path from the Account panel through the API to the data layer, so it's available on any plan today. It's also useful sooner than "sharing a workspace with a teammate" might suggest: the free tier already allows up to two workspaces on one account, so even a solo user keeping, say, a personal board and a separate one can wire an agent to just one of them without inviting anyone or upgrading.

How this fits with read-only and project-scoped tokens

All three axes narrow what a credential is allowed to do or reach; they don't replace the approval gate, which separately controls what an agent can finish without a human signing off. Use workspace scoping when the unit you want to hand an agent is "this whole shared board," project scoping when it's narrower than that, and read-only on top of either when the agent should only watch. Running more than one agent against a shared account gets easier to reason about once each token's reach is written down in the credential itself rather than in a policy nobody's re-checking.