Connect an agent

Schematic Planner speaks MCP over HTTP. There is nothing to install: open Agents in your account settings, create a key, and paste the URL and key into your client.

A key belongs to you rather than to one workspace, so a single key reaches every workspace you are a member of. Where that leaves a choice, the tools take a workspace argument — and asked to create something without one, the server names the options instead of guessing.

{
  "mcpServers": {
    "schematic-planner": {
      "type": "http",
      "url": "https://your-instance.example/mcp",
      "headers": { "Authorization": "Bearer sp_..." }
    }
  }
}

The tools

list_workspaces: Workspaces this key can act in.
list_projects: Projects it can reach, across the account or narrowed to one workspace.
list_plans: Plans, grouped by workspace, project and folder, each with the link to open it.
search: Looks for words across every plan the key can reach — titles, slugs, tags and details — and answers with the plans they are in. Use it before drawing something new: a second plan of a system somebody already drew is how a workspace turns into a pile.
trace: Follow the flow through one part of a plan — what a node reaches, or what reaches it, hop by hop, with what sets each hop off and what it carries. The way to read a plan: it answers with the thread rather than the whole document, and a cycle is reported instead of followed round.
get_plan: The whole plan at once. Outline, graph JSON, or the full Markdown. Never coordinates. The answer ends with the kinds and statuses the project uses, so an agent knows which words it has.
read_nodes: The full detail of the nodes you name, as Markdown, with what each one is wired to and what holds it.
next_task: Where the plan has got to and what can be started now, each with its detail. It goes by what each status means rather than by its name: work already under way, work that is blocked, and work that is ready because everything before it is finished or given up.
validate: Checks a plan against rules that hold for any plan: a dependency cycle, a node connected to nothing, work outside every flow, and kinds or statuses the project does not define. It only reads; fixes go through apply_ops.
plan_history: Who changed what, newest first — people and agents alike.
create_project: A new project to draw in.
create_plan: Opens an empty plan, filed in a folder by its path if you give one. The first call, not the last: it answers with an id, the address the plan can be looked at, and the kinds and statuses the project uses.
apply_ops: How a plan grows after that, and the only write door. Batched, atomic, keyed by slug so retries are safe — and each batch reaches every open canvas at once, so a person looking at the plan watches it change rather than being handed a finished picture. Kinds and statuses are checked against the project: one it does not have refuses the whole batch, with the ones it does listed.
set_plan_sources: Which plans this one was written from. Reading the plan back says whether each one is still there.
layout: Re-arrange. Nodes a person dragged are left where they are.
export_plan: The Markdown bundle, plus a link to the zip.
delete_plan: Moves one to the workspace trash, where a person can restore it. Requires its title typed back, so a wrong id cannot take somebody else’s work.
list_folders: The folders in a project, each by its path, such as Specs/Billing, with how many plans are filed in it.
create_folder: Makes a folder. Give a path to make one inside another, and any folder on the way that is missing is made too. Asked for one that is already there, it hands that one back.
rename_folder: Renames a folder. It stays where it is, and so does everything in it.
delete_folder: Moves a folder to the trash with the folders and plans inside it, which all come back with it. Requires its name typed back.
move_plan: Files a plan somewhere else: another folder, another project, or a project in another workspace, which drops its share link.

Folders are addressed by path

Folders nest, so a tool that takes a folder takes its path from the top of the project: Specs/Billing. A bare name still works when only one folder in the project has it, so prompts written before folders nested keep working. A name two folders share is refused with both paths rather than guessed at.

Kinds and statuses are the project’s

Each project defines its own kinds and statuses, and every plan in it uses them. An agent reads them in the answer to get_plan or create_plan and writes their ids; a name works too. A project nobody has changed has the built-in ones — idea, planned, in_progress, blocked, done, dropped, and feature, task, decision, note, group. A value the project does not have is refused with the list of those it does. Agents use the vocabulary but cannot change it; that is done in the project’s settings.

A node’s detail is written in a block editor in the app, and an agent reads and writes it as Markdown. Tables, toggles and callouts come through as a Markdown table, a <details> block and an Obsidian callout.

Why agents do not set positions

A language model asked for coordinates produces a diagram nobody wants to read, and spends your context doing it. So the tools have no position field. An agent says what flows where; the server runs the layout, and places the writing on each line too. Anything a person has dragged is pinned, and automatic layout never touches it again.

What the export contains

Flows are written into each node's front matter, with what sets them off and what they carry. Containment edges become directory nesting. Dependency edges become a topological order, which becomes the numeric prefix on each filename. Every node carries its own frontmatter, so the bundle describes the graph completely rather than rendering a picture of it. A dependency cycle does not block the export: it is broken in a stable way and reported in the README.