# Plansmith MCP server

Give a coding agent the plan it is meant to build from, with document discussions, suggestions and notification tools.



## Hosted [#hosted]

Hosted and stdio MCP expose document collaboration and Inbox tools. Use the returned document
capabilities and revisions when creating a thread, suggesting an edit or reviewing one. A write
credential is required for mutations; source permissions still decide who can accept an edit.
See [Comments and suggested edits](/docs/comments-and-suggestions) for the shared behavior.

```json
{
  "mcpServers": {
    "plansmith": {
      "url": "https://mcp.plansmith.co"
    }
  }
}
```

Your client discovers how to authorize on its own and sends you to a consent screen the first time.
Nothing to paste.

## Local [#local]

```json
{
  "mcpServers": {
    "plansmith": {
      "command": "plansmith",
      "args": ["mcp"]
    }
  }
}
```

Runs on your machine and reuses the session from `plansmith auth`. Useful when the agent is already
local and you would rather not authorize a second connection.

## What the agent can do [#what-the-agent-can-do]

Read the plan and build from it: list projects and plans, pull a whole plan tree in one call, read a
Spec with its numbered acceptance criteria, export a plan as markdown, and read the prototype
template in force (`plansmith_get_prototype_template`).

`plansmith_get_prototype` reads a plan's prototype. By default it returns the status, the size and
whether the specs changed since the prototype was built. Pass `html: true` for the document itself,
and add `standalone: true` for a page that opens safely on its own in a browser: the prototype runs
inside the same sandbox the app uses. The local server also takes `save: true`: it saves the
document as a new file in a private temp folder and returns the path instead of the document, so a
large prototype stays out of the agent's context. It never writes to a path the caller names.

Read and manage sharing: `plansmith_get_plan_sharing` reports who a plan is shared with, whether it
is a sub-plan, and which plan controls its sharing. Three tools change it:
`plansmith_set_plan_visibility`, `plansmith_add_plan_collaborator` and
`plansmith_remove_plan_collaborator`. All three are writes, so they need a `write` credential.

Sharing lives on the top-level plan and covers every sub-plan under it, so a change addressed at a
sub-plan lands on the plan above it. Every sharing response carries a `scopeNote` naming that plan.

Both servers also expose `plansmith_get_format`, `plansmith_set_format`, and
`plansmith_reset_format` for spec and epic formats. Omit `project` for company scope or supply a
project slug. Reads include source and scope document links and `overrideRevision`. Only workspace
owners can set or reset formats at either scope, with a write credential and an active workspace.
Set and reset require `expectedRevision` from the read, including explicit `null` for absence.
If a newer edit causes a conflict, read and review it before trying again. Reset returns the
inherited format now in force.

Use `plansmith_read_discussion` to resolve a document, read threads, replies and suggestion history,
or find mention candidates. `plansmith_update_discussion` creates threads and replies, edits or
deletes comments, resolves or reopens threads, reattaches passages, manages subscriptions and
creates or reviews suggested edits. Reuse the same `input.requestId` on retry and supply the
returned `expectedVersion` for edits and decisions. A viewer with a write credential can comment
and suggest; accepting an edit still requires permission to maintain the source document.

For incremental thread refreshes, pass `knownRevisions` from the previous `list-threads` response.
The returned `order` contains the current page's thread IDs; `threads` contains only changed
threads. Retain unchanged threads by ID and replace the page order. Access and capabilities are
checked on every refresh. Omit `knownRevisions` to fetch the complete page.

`plansmith_list_notifications` reads your Inbox; `plansmith_get_notification` reads one item.
`plansmith_mark_notification` marks an item read
or unread, and `plansmith_mark_all_notifications_read` clears unread items through the returned
sequence. `plansmith_get_notification_preferences` reads your email choices;
`plansmith_set_notification_preferences` changes them. These tools act only on your own Inbox.

`plansmith_add_image` adds an image to a plan and, with `spec` or `epic`, to the end of that
document. It returns the `![alt](url)` markdown so the agent can place the image anywhere else too.
The hosted server takes a public https `url` (8 MB) or base64 `data` (3 MB); the local server also
takes a file `path` up to 10 MB. If the document changed since the agent read it, the error carries
`attachment_id`: pass it back instead of uploading again.

Hosted writes cover sharing, formats, document collaboration, images and Inbox preferences. To let an agent create plans and specs, set a
status, write an epic, attach context, push to your issue tracker, replace or reset the prototype
template (`plansmith_set_prototype_template`, `plansmith_reset_prototype_template`) or rebuild a
prototype in the current template (`plansmith_rebuild_prototype`), run the local server instead: it
acts under the session you just created rather than a connection you authorized months ago.

<Callout>
  An agent connected this way acts as you. It can reach exactly the plans you can reach, and a
  read-only credential can never change anything. Revoke a connection any time in Settings → API keys.
</Callout>

## A good first prompt [#a-good-first-prompt]

```text
Read PLAN-12 in the recipe-box project from Plansmith and
implement SPEC-1, following its acceptance criteria exactly.
```