> ## Documentation Index > Fetch the complete documentation index at: https://help.plannotator.ai/llms.txt > Use this file to discover all available pages before exploring further. # Connect an Agent to Workspaces with MCP > Connect an MCP client to Workspaces with an API key and use the current document, annotation, version, and artifact tools. Connect an agent to your instance's `POST /mcp` endpoint with a Workspaces API key. Set the client to use Streamable HTTP. This connection does not use a browser session or share link. Use the instance's public API origin. Hosted Workspaces and the default container setup use the app origin. A Cloudflare self-hosted deployment uses its separate public API origin, not the Access-protected app origin. ## Before you connect You need: * A Workspaces account. * A [Workspaces API key](/workspaces/agents/api-keys). * Your Workspaces public API origin. * An MCP client that supports Streamable HTTP and request headers. ## Add the server to your client Add a server with these fields to your client's MCP settings: | Field | Value | | ------------ | --------------------------------------------------------------------------------- | | Transport | Streamable HTTP | | URL | `https://your-workspaces-host.example/mcp` | | Header name | `Authorization` | | Header value | `Bearer `; the reference must resolve to the Workspaces API key | Clients store settings and secrets in different ways. Use this table as a field list, not as a configuration file. Do not save the raw key in a file you share or commit. Save the setting, then restart or reconnect the client. After it connects, the client lists the tools that this Workspaces instance supports. ## Available tools | Task | Tools | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Find and read documents | `workspaces.list_workspaces`, `workspaces.list_documents`, `workspaces.read_document` | | Create and edit documents | `workspaces.create_document`, `workspaces.update_document` | | Use document history | `workspaces.list_versions`, `workspaces.restore_version` | | Discuss documents | `workspaces.list_annotations`, `workspaces.create_annotation`, `workspaces.create_reply`, `workspaces.resolve_annotation` | | Publish and read artifacts | `workspaces.publish_artifact`, `workspaces.list_artifacts`, `workspaces.get_artifact`, `workspaces.list_artifact_versions` | Follow the tool schemas your MCP client returns. Do not assume that a REST API route or an old tool list 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. After a hosted 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 on hosted or self-hosted Workspaces. 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 this instance does not support. | Update the client or set it to a protocol version accepted by the instance. | | `401 Unauthorized` | The key is missing, invalid, or revoked. | Create or select an active API key and send it as a Bearer token. | | `403 Invalid Origin header` | The client's `Origin` header did not pass the instance's origin check. | If the client can omit `Origin`, omit it. Otherwise, set `Origin` to the Workspaces app origin: the same scheme, host, and port as `APP_ORIGIN`. Local and development instances also accept the request URL's origin and origins on `localhost`, `127.0.0.1`, or `[::1]`. For a self-hosted instance, `APP_ORIGIN` must be the Workspaces app origin, not the MCP client's. | | `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 key 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 July 22, 2026. Maintained by the Plannotator documentation team.*