What is MCP?
The Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. Instead of copy-pasting context into a chat window, MCP gives your AI direct access to the systems you work with.
Cartographer exposes a remote MCP server at https://cartographer.studio/mcp. Any MCP-compatible client can connect to it and interact with your spaces, projects, and cards using natural language.
Connect your AI tool
Each client has its own short setup guide. All of them use the same server URL and sign in with OAuth, so there are no API keys to manage.
- Connect Claude: Claude Desktop and claude.ai, Claude Code, and the Claude Cowork plugin.
- Connect ChatGPT: ChatGPT with Developer Mode, and the Codex CLI.
Other MCP clients
The server is a remote HTTP MCP endpoint secured with OAuth 2.0. No API keys or environment variables are needed.
Copy the server URL
Any client that supports the Model Context Protocol can connect using this URL:
https://cartographer.studio/mcpAdd it to your client
Look for an MCP or "remote server" option in your client's settings and paste the URL above.
Authorize
On first connection your client opens a browser window to authorize access. All operations are scoped to your active organization.
Your client needs to support OAuth sign-in and structured tool output, which was added in the June 2025 revision of the MCP spec. See Tool responses for what the server sends back.
Available Tools
The MCP server has a comprehensive tool suite that covers the full story mapping workflow, including full create/list/get/update/delete coverage for every entity. Every tool checks its inputs, enforces access control for your organization, and returns structured data your AI can use.
Spaces & Statuses
| Tool | Description |
|---|---|
| spaces_list | List all spaces in your organization. |
| spaces_get | Get a single space by ID. |
| spaces_create | Create a new space with a name and optional description. |
| spaces_update | Update a space’s name or description. |
| spaces_delete | Soft-delete a space. Call once without confirm to preview how many projects, personas, and customers will become inaccessible; call again with confirm: true to actually delete. |
| spaces_projects_list | List all projects within a space. |
| spaces_statuses_list | List available workflow statuses for a space (e.g. Backlog, In Progress, Done). Use the returned IDs when creating or updating cards. |
| statuses_create | Create a new workflow status in a space, with a six-digit hex color (e.g. #3B82F6) and a category: backlog, unstarted, started, completed, or canceled. |
| statuses_get | Get a single status by ID. |
| statuses_update | Update a status’s name, color, or category. Cards already using the status keep it. |
| statuses_delete | Soft-delete a workflow status. Cards already using it keep a stale statusId until you reassign them with cards_update. |
Projects
| Tool | Description |
|---|---|
| projects_list | List all projects in your organization, optionally filtered to one space. |
| find_project_by_name | Find projects by a case-insensitive name match, optionally within one space. |
| projects_create | Create a new project in a space. |
| projects_update | Update a project’s name or description. |
| projects_delete | Soft-delete a project. Call once without confirm to preview how many cards, milestones, and comments will become inaccessible; call again with confirm: true to actually delete. Canvases in the parent space are not affected. |
| projects_list_backbone | Return journeys and their steps with a count of story cards under each step, plus the project’s milestones. A quick structural overview of the map. |
| projects_list_all_cards | Return every card with its tier, parent, milestone, status, and dates, plus the project’s milestones. Paginated — keep passing the response’s nextCursor back as cursor until it comes back null to see every card. |
| projects_get_card_details | Get full details for one card: description, status, estimate, dates, persona and customer IDs, its milestone, comments, and child cards. |
Cards
A story map has three tiers of cards. Journeys (tier 1) are the columns across the top, steps (tier 2) break each journey into phases, and story cards (tier 3) sit under a step, either in a milestone row or in the backlog. Each story card has a type: none, objective, risk, question, knowledge_gap, learn, pain_point, or opportunity.
Story cards can also have a status, an estimate (a whole number or a t-shirt size from XS to XL), and start and target dates in YYYY-MM-DD format that show on the Gantt view.
| Tool | Description |
|---|---|
| cards_bulk_create | Create many items in one call: a nested tree of journeys, steps, and story cards plus milestones, or new steps and cards under existing parents. The whole batch is validated before anything is created. The preferred way to build more than a couple of cards. |
| journeys_create | Create a tier-1 journey column on the project. |
| steps_create | Create a tier-2 step within a journey. |
| story_cards_create | Create a tier-3 story card within a step, with an optional type, status, estimate, dates, milestone, and color. |
| cards_create | Low-level card creation with manual parent and type management. |
| cards_update | Update a card’s title, description, type, status, estimate, dates, or color. Use cards_move to change its parent or milestone. |
| cards_move | Move a card directly above or below another card, or to the top or bottom of a section (a parent and milestone). This is how you change a card’s parent or milestone. |
| cards_delete | Soft-delete a card (cards with children cannot be deleted). |
| cards_bulk_delete | Soft-delete many cards in one call, cascading through the steps and story cards under them. Preview first, then confirm. |
Milestones & Comments
| Tool | Description |
|---|---|
| milestones_list | List all milestones for a project. |
| milestones_get | Get a single milestone by ID. |
| milestones_create | Create a milestone row, with optional start and target dates in YYYY-MM-DD format. |
| milestones_update | Update a milestone’s title, description, or dates. |
| milestones_delete | Delete a milestone. Cards previously assigned to it keep a stale milestoneId until you move them with cards_move. |
| comments_list | List comments on a project, optionally filtered to one card or milestone. Paginated. |
| comments_get | Get a single comment by ID. |
| comments_create | Add a comment to a card or a milestone (one or the other, not both), or reply to an existing comment. |
| comments_update | Edit a comment’s content. Restricted to the comment’s original author or an organization owner/admin. |
| comments_delete | Delete a comment. Restricted to the comment’s original author or an organization owner/admin. |
| comments_resolve | Mark a top-level comment thread resolved, optionally pointing to the reply that resolved it. |
Personas & Customers
| Tool | Description |
|---|---|
| personas_list | List all personas in a space. |
| personas_get | Get a single persona by ID. |
| personas_create | Create a persona (user archetype) in a space. |
| personas_update | Update a persona’s name, description, or color. |
| personas_delete | Soft-delete a persona. |
| customers_list | List all customers in a space. |
| customers_get | Get a single customer by ID. |
| customers_create | Create a customer (company or segment) in a space. |
| customers_update | Update a customer’s name, description, or color. |
| customers_delete | Soft-delete a customer. |
| cards_personas_set | Associate personas with a card, replacing existing associations. Pass an empty list to clear them. |
| cards_customers_set | Associate customers with a card, replacing existing associations. Pass an empty list to clear them. |
Canvases
| Tool | Description |
|---|---|
| canvases_list | List the whiteboard canvases in a space. Paginated. |
| canvases_get | Get a canvas’s details plus how many elements and files it holds (not the drawing itself). |
| canvases_create | Create a new whiteboard canvas in a space. |
| canvases_update | Rename a canvas. The drawing itself is edited in the canvas editor. |
| canvases_delete | Soft-delete a canvas and its contents. Cards it was attached to simply lose the attachment. |
| canvases_attach_to_card | Attach a canvas to a card. Attaching a canvas that is already attached changes nothing. |
| canvases_detach_from_card | Detach a canvas from a card. |
Other
| Tool | Description |
|---|---|
| whoami | Report the caller’s organization role and whether they have read-only access. |
| feedback_submit | Report a tool that errored, a missing capability, or something confusing to the Cartographer team. Works for viewers and without a subscription. |
Tool responses
Every tool publishes an output schema next to its input schema, so your AI client knows the exact shape of a result before it calls the tool. Successful calls return the result as structured content under a data key, including list tools that return an array. For example, spaces_get returns:
{
"content": [],
"structuredContent": {
"data": {
"id": "3f2a9c1e-7b4d-4e8a-9c21-5d6f0a8b7e14",
"name": "Mobile App",
"description": "Everything for the iOS and Android apps",
"createdAt": "2026-03-02T09:14:00.000Z",
"updatedAt": "2026-09-18T16:42:11.000Z"
}
}
}The result is not repeated as a JSON text block, so a client that only reads text content will show an empty result.
Pagination
projects_list_all_cards, comments_list, and canvases_list return one page at a time: 200 items by default, or up to 500 with limit. Each page includes total and nextCursor. Pass nextCursor back as cursor to get the next page, until it comes back null.
Errors
Arguments that don’t match a tool’s input schema are rejected before the tool runs. Other failures come back flagged with isError, with a JSON error in the text content. The error has a machine-readable code and a human-readable message:
{
"isError": true,
"content": [
{
"type": "text",
"text": "{ \"code\": \"CARD_NOT_FOUND\", \"message\": \"Card not found\" }"
}
]
}Common codes include:
CARD_NOT_FOUND,PROJECT_NOT_FOUND_OR_ACCESS_DENIED, and other*_NOT_FOUNDcodes: the ID doesn’t exist or isn’t in your organization.VIEWER_READ_ONLY: you’re a viewer and the tool changes data.COMMENT_FORBIDDEN: only a comment’s author or an organization owner/admin can edit or delete it.CARD_HAS_CHILDREN:cards_deleteonly removes cards with nothing under them. Usecards_bulk_deleteto delete a card and its children.SUBSCRIPTION_REQUIRED: your organization needs an active subscription or trial.
Titles and hints
Each tool has a readable title for clients to display, such as “Bulk create cards” for cards_bulk_create. Each tool also has hints about what it does. Every list and get tool, along with whoami and find_project_by_name, is marked read-only. Delete tools and canvases_detach_from_card are marked destructive. Clients can use these hints to decide when to ask you before running a tool. No tool reaches outside your Cartographer organization.
Authentication
The MCP server uses OAuth 2.0 for authentication. When you connect a new client, you are redirected to Cartographer to sign in and approve the connection. The consent screen shows exactly what the client is asking for:
- Access and create spaces
- Access and create projects
- Create, update, move, and delete cards
Clients find the sign-in server on their own. The server publishes protected resource metadata at /.well-known/oauth-protected-resource, as the MCP authorization spec expects, so there is nothing to configure beyond the server URL.
You can revoke access at any time from your profile settings.
Permissions
All operations are scoped to your active organization. The server checks access on every request. A connected client can only see and change resources you have access to.
Organization viewers can use every read-only tool. Tools that change data return a VIEWER_READ_ONLY error for viewers. Call whoami to check your role. Using the MCP server requires an active subscription or trial.
