Octopus MCP

Once connected, your agent can:

• See your work — list your projects and workspaces, and read the full structure of a sitemap (pages, blocks, colors, tags, symbols).
• Build and edit sitemaps — create and update pages, add content blocks with wireframes, restructure the page tree, apply several changes at once as a single atomic update.
• Read and leave review notes — read the comments on pages and blocks and the threads pinned to the canvas, add notes and replies, and resolve or reopen a thread. A note left by an agent is authored by your account and looks exactly like one you typed, and posting it notifies nobody.
• Manage projects — create, duplicate, archive, move projects; transfer ownership; update project settings like theme and layout. Projects cannot be deleted over MCP — archiving is as far as an agent goes, and archives are reversible.

Every action runs as you — the agent only ever sees and changes what your Octopus.do account has access to.

Connecting

Endpoint

https://mcp.octopus.do/mcp

The general flow is the same in every client:

1. Add Octopus as a remote MCP server / connector using the endpoint above.
2. Choose OAuth as the authorization type — most clients detect this automatically.
3. Sign in (or register) with your Octopus.do account when the browser opens.
4. Ask your agent to do something — e.g. “show my Octopus projects” or “add a pricing page to my sitemap.”

No API keys to copy or manage — authorization happens through your normal Octopus.do login. Client-specific instructions below.

Claude (web and desktop)

1. Go to Settings → Connectors → Add custom connector.
2. Enter https://mcp.octopus.do/mcp as the URL and click Add.
3. Click Connect and sign in with your Octopus.do account.

Claude Code

Run in your terminal:

claude mcp add --transport http octopus https://mcp.octopus.do/mcp

Then run /mcp inside Claude Code to complete the sign-in.

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "octopus": {
      "url": "https://mcp.octopus.do/mcp"
    }
  }
}

Cursor will prompt you to authenticate the first time the server is used.

VS Code (GitHub Copilot)

Run MCP: Add Server from the Command Palette and choose HTTP, or add to .vscode/mcp.json:

{
  "servers": {
    "octopus": {
      "type": "http",
      "url": "https://mcp.octopus.do/mcp"
    }
  }
}

ChatGPT

Octopus.do is published in the ChatGPT app directory: search for Octopus.do under Settings → Apps & Connectors and press Connect. Requires ChatGPT Plus or higher. Full walkthrough: Octopus.do for ChatGPT.

To add the MCP endpoint by hand instead — for a dev environment, or a workspace where the app isn't available — turn on developer mode (Settings → Apps & Connectors → Advanced settings) and:

1. Go to Settings → Apps & Connectors → Create (or Add connector).
2. Set the MCP server URL to https://mcp.octopus.do/mcp and authentication to OAuth.
3. Complete the Octopus.do sign-in when prompted.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "octopus": {
      "serverUrl": "https://mcp.octopus.do/mcp"
    }
  }
}

Other MCP clients

Any client that supports remote MCP servers (Streamable HTTP) with OAuth works: point it at https://mcp.octopus.do/mcp, pick OAuth, and sign in with your Octopus.do account.

Authentication

Octopus MCP uses OAuth 2.1, the standard MCP clients use for secure, per-user authorization. Your agent requests access on your behalf, you approve it once during sign-in, and access can be revoked from your Octopus.do account at any time. The MCP server itself never sees or stores your password.

Available tools

Your agent picks these tools on its own — you don’t call them directly. The reference below is useful when you want to know exactly what the agent can (and can’t) do, or to phrase a request precisely.

Most write tools accept an optional idempotency_key (string): a unique key that makes retries safe — a repeated request with the same key is applied only once. It’s omitted from the tables below.

Destructive actions (like deleting a page, a block or a comment) are flagged to your AI client, which will typically confirm with you before running them.

Reading

get_me

Returns your account name. No parameters.

list_projects

Lists the projects you can access, across every workspace (personal and teams), most recently updated first. Each item includes the workspace it belongs to. One page at a time: total is how many matched and has_more whether any were left out. To find one project by name use q rather than paging — it searches every project on the account, not just the current page.

list_workspaces

Lists your workspaces (personal + teams) with their folders and the 10 most recently updated projects in each — project_count gives the real total, and list_projects searches and pages through the rest. No parameters.

get_workspace

Returns one workspace: info, folders, and projects.

get_project

Returns the state of one project: the entities (tabs, sections, nodes = pages, blocks, colors, tags, symbols, arrows, …) and the parent/child tree linking them. A whole sitemap is a large read, so start with view: "outline" and narrow further with scope_id when you only need one branch.

list_comments

Reads the review notes on a project. There are two kinds and one call returns both: flat comments left on pages and on content blocks (thread replies are comments too), and canvas threads — the pins on the sitemap canvas, which carry a position and an open/resolved state. The result has a comments array and a threads array; whichever was not asked for comes back empty. Threads default to the open ones, so the default answer is what is still outstanding rather than everything ever written.

No access shows up differently depending on what was asked for. A default call reads both halves, and the threads half is refused outright, so the whole call fails and says so. A comments-only call (a kind of page, block or reply) gets an empty list instead — the underlying endpoint answers 200 with nothing rather than a 403, and no caller can tell that from a project that simply has no notes.

An anchor.type of null on a thread means the page or tab it was pinned to has been deleted and the pin outlived it — orphaned pins are normal. content comes back exactly as it was written: a Plate/Slate document serialized to a JSON string, or plain text. author is an opaque user uuid — never a name, an email or an avatar — and null when the note was left by an anonymous commenter.

Editing

apply_changes

Applies several editing operations to a project as one atomic change — the preferred way to build or restructure a sitemap. Operations run in order and each sees the effect of the previous ones. Give a created entity a ref and reference it in later operations via parent_ref / node_ref instead of an id.

Each operation:

A successful response may also carry warnings — advisory notes such as a page whose url does not sit under its parent's path. Nothing was blocked and no retry is needed; they are there to be read, not acted on automatically.

Operation names follow group.action:

Both halves of the name are snake_case — tags.assign_node, sections.move_up, nodes.replace_url_prefix. The REST endpoint for the same operation spells its path with hyphens (/tags/assign-node); the two forms are not interchangeable, and an operation named in path form is rejected.

The REST API has a few operations the MCP server deliberately does not offer — estimates (money), tab reordering, symbol linking and external links. They stay available over the Public API.

create_node

Creates a page (node) in the sitemap.

update_node

Updates page fields.

move_node

Moves a page with its whole subtree to another parent.

delete_node

Deletes a page with its whole subtree and all blocks inside.

create_block

Creates a content block inside a page.

update_block

Updates block fields.

move_block

Moves a block to another page.

delete_block

Deletes a block from its page.

manage_comment

Adds, deletes, resolves and reopens comments and canvas threads. A note added this way is authored by the account the connection is signed in as, with no marker of any kind — in the editor it is indistinguishable from one that person typed — and it notifies nobody, because no mentions are sent.

What add creates depends on the target type and on whether a position is given:

Every id is checked against the project before anything is written — on add, on delete, and on resolve and reopen alike — so an id the project does not contain fails rather than creating a note attached to nothing or closing a thread somewhere else. An id of the wrong kind, a block id given as a page for instance, is refused with the id's real kind named. Neither is worth a retry: the fix is to re-read the ids.

Only canvas threads have a resolved state, so resolve and reopen take a thread id — a page or block comment cannot be resolved at all. delete takes either a comment id or a thread id and works out which it is, so the caller does not have to know; deleting a thread removes the pin but leaves its replies behind, since they are comments in their own right.

The optional idempotency_key makes a retry safe — the same key sent twice adds one note, not two. It does not make add idempotent: two add calls with different keys add two notes. On delete the key is accepted and ignored: there is nothing to protect, because deleting the same id twice removes one note and then reports it gone.

Project management

create_project

Creates a new project in the target workspace. May fail when your plan’s project limit is reached.

manage_project

Project lifecycle actions: duplicate, archive/unarchive, move, transfer.

update_project_settings

Updates project-level settings.

Learn more

• Octopus.do: https://octopus.do/
• Model Context Protocol: https://modelcontextprotocol.io/