Connect an Agent to Workspaces with MCP

Add the Workspaces MCP server to your client, then sign in through the client’s browser flow. You do not need an API key.

claude mcp add --transport http workspaces https://workspaces.plannotator.ai/mcp
claude mcp login workspaces

Approve the request in the browser window that opens. Use an API key only for scripts, CI, and clients that cannot complete the browser sign-in.

Before you connect

You need:

A Workspaces account.
An MCP client that supports Streamable HTTP.

The server URL is https://workspaces.plannotator.ai/mcp. The endpoint accepts POST requests only. Add the server with no credential, then run the client’s own sign-in step.

Claude Code
Codex
Cursor and other clients

claude mcp add --transport http workspaces https://workspaces.plannotator.ai/mcp

Then run claude mcp login workspaces, or open Claude Code and run /mcp. Approve the request in the browser window that opens.

Add this to ~/.codex/config.toml:

[mcp_servers.workspaces]
url = "https://workspaces.plannotator.ai/mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60

Then run codex mcp login workspaces and approve the request in the browser.

Add a server entry with the URL and no header:

{ "mcpServers": { "workspaces": { "url": "https://workspaces.plannotator.ai/mcp" } } }

Then use the client’s own sign-in step and approve the request in the browser.

The sign-in creates a Workspaces API key that you own. It appears under Settings, then API keys, marked via OAuth. Revoke it there to disconnect the client.

Connect with an API key

Use this route for scripts, CI, and clients that cannot complete the browser sign-in. Create a Workspaces API key, then send it as a bearer header:

claude mcp add --transport http workspaces https://workspaces.plannotator.ai/mcp \
  --header "Authorization: Bearer wsk_live_..."

For another client, add a remote Streamable HTTP server at https://workspaces.plannotator.ai/mcp with an Authorization header set to Bearer followed by the key. Store the key with the client’s secret storage. Do not save the raw key in a file you share or commit.

Available tools

Tool names start with workspaces.. Your client reads the current list from the server’s tools/list response, and that list is the authority.

Task	Tools
Check the connection	`workspaces.whoami`
Find and manage workspaces	`workspaces.list_workspaces`, `workspaces.create_workspace`, `workspaces.update_workspace`, `workspaces.claim_workspace`, `workspaces.request_workspace_approval`, `workspaces.delete_workspace`, `workspaces.get_activity`
Find and read files	`workspaces.list_files`, `workspaces.read_file`
Create and edit files	`workspaces.publish_file`, `workspaces.update_document`, `workspaces.delete_file`
Use file history	`workspaces.list_versions`; restore a version with `workspaces.update_document`
Discuss documents	`workspaces.list_annotations`, `workspaces.create_annotation`, `workspaces.update_annotation`, `workspaces.delete_annotation`, `workspaces.list_people`
Read notifications	`workspaces.list_notifications`, `workspaces.dismiss_notifications`
Track work and decisions	`workspaces.list_work_items`, `workspaces.create_work_item`, `workspaces.update_work_item`, `workspaces.list_decisions`, `workspaces.create_decision`, `workspaces.update_decision`
Other	`workspaces.resolve_external_ref`, `workspaces.link_preview_image`, `workspaces.get_guide_brief`, `workspaces.submit_guide`

A file is a document or a published asset, such as an image or a PDF. workspaces.create_annotation also posts replies, and workspaces.update_annotation resolves and reopens threads. Follow the tool schemas your MCP client returns. Do not assume that a REST API route has an MCP equivalent.

Access and change records

The agent uses the key owner’s workspace ownership and current organization memberships. It does not inherit access from share links the owner has opened. Workspaces records the key and its owner with each change. Revoking the key stops MCP access. This applies to keys created by browser sign-in as well. After an organization removes the key owner, access granted by membership usually ends within 60 seconds. If Workspaces cannot refresh the membership list, cached access may last up to 10 minutes. Workspaces also gives the person’s organization workspaces to the admin who removes them, so the key loses owner access to those workspaces. The key remains active for personal workspaces, other organization memberships, and workspaces that are public or open to anyone with the link. Blocking sign-in does not revoke the key. Only the key owner can revoke it.

Fix connection errors

Result	Cause	Recovery
`400` with an unsupported protocol-version message	The client sent an `MCP-Protocol-Version` that Workspaces does not support.	Update the client or set it to a supported protocol version.
`401 Unauthorized`	The client has not signed in, or its key is missing, invalid, or revoked.	Run the client’s sign-in step again, such as `claude mcp login workspaces`. With an API key, create or select an active key and send it as a Bearer token.
`403 Invalid Origin header`	The client’s `Origin` header did not pass the Workspaces origin check.	If the client can omit `Origin`, omit it. Otherwise, set `Origin` to `https://workspaces.plannotator.ai`.
`405` for `GET` or `DELETE`	The server accepts MCP requests through `POST /mcp` only.	Configure the client for Streamable HTTP instead of opening the endpoint in a browser.
Tool error	The signed-in person lacks access, the input does not match the tool schema, or the resource no longer exists.	Check the tool input and confirm that the key owner can open the workspace.

Reviewed October 15, 2026. Maintained by the Plannotator documentation team.

Start

Accounts and organizations

Sharing and access

Documents and collaboration

Agents and developer access

Plans, billing, and seats

Security and privacy

Troubleshooting

Before you connect

Connect with an API key

Available tools

Access and change records

Fix connection errors

​Before you connect

​Connect with browser sign-in

​Connect with an API key

​Available tools

​Access and change records

​Fix connection errors

Before you connect

Connect with browser sign-in

Connect with an API key

Available tools

Access and change records

Fix connection errors