How PlanStack works

01 Overview

AI coding agents are great at producing implementation plans — and those plans usually die in chat scrollback the moment the next message arrives. They aren't addressable, they aren't shareable with teammates who don't have the agent open, and a second agent (or the same agent tomorrow) can't pick up where the first one left off.

PlanStack gives plans a permanent home. An agent connects over the Model Context Protocol (MCP), publishes a plan, and gets back a stable, public URL. Every revision is a new immutable version at that same link. The plan becomes a first-class artifact: re-consumable by other agents as context, and readable by any human with the URL — no login, no install.

02 How it works

The core loop is four moves:

1. Draft. Your agent writes the plan as semantic HTML — headings, lists, tables, code blocks. No styling required.
2. Publish. The agent calls publish_plan over MCP. PlanStack applies the house theme, stores an immutable version, and returns a stable URL like planstack.dev/p/k3f9qm2p.
3. Share & hand off. Send the URL to a teammate (it just renders), or hand the plan id to another agent, which pulls the source back with get_plan and keeps working.
4. Revise. Call update_plan to publish a new version at the same URL. The previous version stays reachable at ?v=N — nothing is ever overwritten.

Four properties make that loop useful:

• Immutable version history. Every publish is a permanent version. ?v=1 always shows v1; the bare link always shows the latest.
• Genuinely public links. Anyone with the URL can read the plan in a fast, themed page. No account, no MCP client.
• Agent-to-agent handoff. One agent plans; another re-consumes it as context. A shared brain across your tools.
• Plan-native theming. A clean house theme is applied at publish time, so every plan is readable by default (more in §08).

03 Use cases

Reach for PlanStack whenever a plan needs to outlive the chat it was born in:

• A review gate before you build. Have the agent publish its plan first. Read it on a real page, comment, then tell it to proceed — instead of approving a wall of text in the terminal.
• Planner → implementer handoff. A "planning" agent publishes; an "implementing" agent (or a fresh session) calls get_plan and executes against the agreed plan. Same context, no copy-paste.
• Share with humans who aren't on the MCP. Drop the link in Slack for a PM, reviewer, or teammate. They see the plan, not your terminal.
• A durable decision record. Because versions are immutable, the link is an audit trail: what was decided, when, and how the plan evolved across revisions.
• Multi-agent fleets. Several agents working a project publish into one place and reference each other's plans by id — a shared working memory.
• Cross-tool continuity. Plan in Claude Code today, continue in Cursor tomorrow. The plan lives at a URL, not inside one tool.

04 Setup

From zero to your first published plan:

1. Create an account. Sign up, then open the dashboard.
2. Issue an API key. Go to Settings → API Keys and create one. It's shown once (stored only as a hash) and is prefixed ps_live_. This key authenticates your agent.
3. Connect your agent over MCP. Add the PlanStack MCP server to your client. The recommended path is the hosted remote endpoint — nothing to install (see §05).
4. Publish your first plan. Ask your agent to draft a plan and publish it: "Draft a plan for the billing refactor and publish it to PlanStack." It calls publish_plan and returns a URL.
5. Open & iterate. Open the URL to read the themed plan. Ask for changes and have the agent call update_plan — a new version appears at the same link.

05 Connecting your agent

PlanStack speaks MCP two ways. Most people want the first.

Remote (recommended) — add a URL

No install or local process is required. Open Settings → API Keys and copy the ready-made MCP configuration for your client. It includes the correct endpoint and authentication header.

{
  "mcpServers": {
    "planstack": {
      "url": "<endpoint from PlanStack settings>",
      "headers": { "Authorization": "Bearer ps_live_…" }
    }
  }
}

Local (optional) — stdio process

Prefer a local process? Run the @planstack/mcp stdio server. It's a thin client that forwards every tool call to the same backend, configured with two environment variables:

{
  "mcpServers": {
    "planstack": {
      "command": "node",
      "args": ["/abs/path/to/planstack/packages/mcp/dist/index.js"],
      "env": {
        "PLANSTACK_API_KEY": "ps_live_…",
        "PLANSTACK_API_URL": "<API URL from PlanStack settings>"
      }
    }
  }
}

Copy both values from PlanStack settings. Remote and local connections expose the same tools.

06 The MCP tools

Connecting exposes four tools. Each returns a short, human-readable summary to the agent; plan accepts either a plan id (e.g. k3f9qm2p) or a full plan URL.

Write plans as semantic HTML — a full document or a bare fragment. The baseline theme is applied automatically at publish, so you never style a plan by hand.

07 Versioning model

Versioning is the heart of PlanStack, and it's deliberately simple:

• The first publish_plan creates version 1 at a fresh URL.
• Each update_plan appends a new immutable version and bumps the "current" pointer. Older versions are never mutated.
• The bare link — /p/<id> — always serves the latest version. A pinned link — /p/<id>?v=N — always serves exactly that version.
• This page's version picker (top right) is the same control: it's how you move between versions of any plan.

On the free tier the latest 10 versions per plan are retained; older ones are pruned. Paid tiers retain full history.

08 Theming & security

PlanStack applies a clean house theme automatically. If your plan includes its own styles, they take precedence, so you can customize the result without rebuilding the baseline reader.

Published content opens in an isolated reader and cannot access your PlanStack account or session. Submissions are capped at 4 MB, with lower limits on some plans.

09 Plans & limits

PlanStack is free to start. The free tier is enough to run the full loop; paid tiers lift limits and add sharing controls.

A 4 MB hard cap applies to every submission regardless of tier. When you hit a limit, the tool call returns a clear message to the agent rather than failing silently. Pro and Team are on the roadmap; today every account is on the free tier.

10 FAQ

Do my teammates need an account?
No. Published plans are public URLs — anyone with the link can read them, no login or MCP client required.

What HTML can I publish?
Any semantic HTML, as a full document or a fragment. PlanStack applies the house theme automatically and opens the result in an isolated reader.

Remote or local (stdio)?
Prefer the remote endpoint — it's hosted, needs no install, and updates with the service. Use stdio only if you specifically want a local process.

Can I make a plan private?
Private, password, and expiring links are on the roadmap (Pro). Today every plan is a public, unguessable URL.

I got a 401 from the MCP server.
Check that your client sends Authorization: Bearer ps_live_… with a valid, un-revoked key. A 402/413 means you hit a tier limit or the 4 MB size cap.

Why didn't an old version change after I revised the plan?
That's by design — versions are immutable. Revisions create a new version; ?v=N always shows the original.

11 Changelog

This document is versioned like any other plan. Its history so far:

• 2026-07-12 — v1. Current documentation: overview, setup, MCP tools, versioning, limits, and FAQ.