Skip to main content
When you authorize an MCP client via OAuth, the grant covers every workspace you’re a member of — not just the one you picked on the consent screen. The picker sets the default workspace; everything else is fluid per request. This is the headline difference between OAuth and the workspace API key path. An API key locks you to one workspace; OAuth lets a single connection drive all of them in the same session — without pasting UUIDs, without restarting your IDE, without separate MCP server entries.
This page is about the OAuth path. Workspace API keys are scoped to a single workspace by design — see Workspace API key for that path.

​
Just use workspace names

You don’t need to know any UUIDs. Ask the AI to list your workspaces once at the start of a session, then refer to them by name from then on:
The AI calls list-my-workspaces and gets back something like:
It keeps that map in conversation context. From here on, just name the workspace in your prompt:
The AI resolves “Acme Sales” → b8c2…, passes it as the workspaceId argument on the crm-search call, and you get the right result. No copy-paste, no config edit.
If you don’t ask first, the AI will call list-my-workspaces itself the moment it needs to disambiguate. The explicit list-at-session-start trick is just a way to front-load the lookup so the first real request doesn’t pause to discover.

​
Default workspace

If you don’t name a workspace in your prompt, the request uses the default — the one you picked on the consent screen when you first authorized. This is what makes casual use frictionless: most prompts don’t need to name a workspace at all. “Draft a reply to the latest email” uses your default. “…in Acme Sales” uses Acme. To change the default, revoke the grant from Settings → Connected apps and re-authorize — the consent screen lets you pick a different default.

​
Discovering workspaces

Already covered above, but worth restating as a one-liner reference:
list-my-workspaces returns name, UUID, and your role on each — useful for sanity-checking access after a permissions change.

​
Permissions

The OAuth grant does not expand what you can access. It inherits whatever workspace memberships your account already has — nothing more. If you ask a tool to act on a workspace you aren’t a member of, the worker returns:
This surfaces in the AI’s response as a tool error. Adding access requires being invited via Workspace settings → Members, not anything on the MCP side.
Removing someone from a workspace does not automatically revoke their OAuth grant for other workspaces they’re in. Their next MCP request targeting the removed workspace returns 403 immediately — Connie re-checks membership on every request — but the same grant still works against any other workspace they belong to. To kill an ex-member’s MCP access across the org entirely, the user themselves can revoke the client in Settings → Connected apps.

​
Advanced: hard-pin a workspace

Most users should ignore this section. The natural-language pattern above is the right default. If you have a specific reason to lock one MCP server entry to one workspace — e.g. a high-stakes prod workspace where you want a hard guardrail that cannot be inferred away by the AI — pin the workspace ID into the URL:
Every request from this MCP entry routes to that workspace; per-tool workspaceId arguments are still respected (so the AI can broaden the scope), but if the AI omits the argument it goes to the pinned workspace, not your OAuth default. Trade-off: you lose the fluid-multi-workspace property OAuth gives you. If you find yourself wanting a hard pin in every server entry, you probably want the workspace API key path instead — that’s exactly what it’s designed for.

​
What’s next

Add more clients

Connect Cursor, Claude Code, and Windsurf alongside Claude Desktop.

Troubleshooting

403s, missing workspaces, default-not-applied.