MCP server

Serving your plans and the plan authoring commands to another agent

graph mcp serve --dir /path/to/project

The point is not to give an agent another set of skills. It is that a plan is a reviewed, validated, versioned pipeline of tool calls — and an agent calling plan_sprint_report gets that whole apparatus behind one tool call, instead of improvising the same sequence differently every time.

For your agent, graph brings deterministic_-ish_ skills.

Configuring a client

{
  "mcpServers": {
    "graph": {
      "command": "graph",
      "args": ["mcp", "serve", "--dir", "/path/to/project"]
    }
  }
}

Pass --dir, or you get only your global setup. Without it the server loads ~/.config/graph/ alone: your global plans are served, but no project’s are.

This is deliberate, not a limitation. An MCP client chooses the working directory the server starts in — you did not. A .graph/ found there can declare [mcp.*] servers graph spawns as child processes, and .graph/tools/*.yaml tools that shell out. Adopting that silently, because a client happened to start in a checked-out repo, would run code you never asked for. So the project layer is opt-in.

Use --dir . when you are launching by hand and mean the current directory.

What is loaded, and when

Layer	Without --dir	With --dir <path>
~/.config/graph/config.toml	loaded	loaded
~/.config/graph/plans, …/tools	loaded	loaded
<path>/.graph/config.toml	ignored	loaded
<path>/.graph/plans, …/tools	ignored	loaded

The global layer is anchored to your home directory, so it does not depend on where anything was started. Only the project layer does, which is why only the project layer requires you to name it.

Writes follow the same rule. The authoring tools (graph_plan_new, graph_plan_draft, graph_plan_set, graph_plan_step_*) write into the first configured plans directory of whichever layer set is active: ~/.config/graph/plans without --dir, and the project’s ./.graph/plans with it. A client’s working directory is never a destination, and no authoring tool takes a path argument — where a plan is written is the user’s decision, expressed with --dir, not the calling agent’s.

[plans].paths replaces the default list rather than adding to it. A project config that pins paths = ["./.graph/plans"] drops ~/.config/graph/plans, and those global plans stop being served.

If the server ends up with no plans at all, it says so — on stderr, and in the MCP instructions the calling model reads, along with the --dir fix.

When the config is broken

A server that dies before the MCP handshake is the worst failure mode this surface has: the client reports “connection failed”, stderr goes to client logs no model reads, and the agent gets nothing to act on. So graph mcp serve never exits over a bad config — it serves anyway and puts the why where the agent will see it:

• A missing provider key (api_key = "${ANTHROPIC_API_KEY}" with the variable unset) doesn’t degrade the server at all. Config loading defers the error to the entry that owns it: authoring tools, graph_plan_list, and plans that run without inference all work, and the calls that do need a model (graph_plan_draft, solver-mode plans) fail naming the variable and the config path that wants it.
• A config that cannot load (parse error, missing variable outside [providers.*]/[mcp.*]) still gets a running server: the load error is appended to the MCP instructions at initialize, and every tool call returns it. The config is re-read per request, so fixing the file or the environment heals the server in place — no restart.

The environment that matters is the one the MCP client launches the server with — a key exported in your shell profile is not necessarily set there. Most clients accept an env block next to command/args in the server entry.

What gets served

Your plans, as tools

Every plan in the catalog becomes plan_<identifier>, carrying that plan’s own input_schema as the tool’s schema, and its description plus exemplars as the routing signal. The calling agent gets exactly the argument contract graph enforces internally — not a generic “run a plan” tool taking a free-form blob.

plan_sprint_report   { team: string, since?: string }
plan_urgent_issues   { }

A plan hidden by requires_servers on this machine is not served, for the same reason it is not offered to graph’s own agent: it cannot run here.

The authoring tools

graph_plan_list, graph_plan_show, graph_plan_validate, graph_plan_new, graph_plan_draft, graph_plan_set, graph_plan_unset, graph_plan_step_add, graph_plan_step_update, graph_plan_step_rename, graph_plan_step_rm, graph_tools_list, graph_tools_show, graph_tools_test.

These give your agent everything it needs to build and check a plan without a shell. Every edit goes through the same validation guard as the command line: an edit that would break the plan is refused, with the problems it would have introduced.

Authoring and calling in one session

The tool list is read fresh on every tools/list, and a successful edit sends notifications/tools/list_changed. So an agent can build a capability and then use it, without a restart:

graph_plan_new       identifier: commit_digest
graph_plan_step_add  E1, builtin__git_log, {…}
graph_plan_set       input_schema, {…}
graph_plan_validate  → { ok: true }
plan_commit_digest   { base: "v1.0", head: "HEAD" }   ← now callable

Cost and latency

graph_plan_draft calls the planner model — roughly 30 seconds, and the only served tool that costs inference. Plans themselves cost whatever their finish mode implies: output-mode plans run with zero inference, solver-mode plans cost one call. Many MCP clients default to a 60-second tool timeout; raise it if your plans are long-running.

Progress and cancellation

Pass a progressToken with a plan_* call and the server reports each step as it runs — the same information plan run prints to a terminal, including the plan call stack when plans compose. Without a token the run is silent, because MCP only permits notifying against a token the client issued.

notifications/progress  { progressToken: "…", progress: 1, message: "E1 builtin__git_log" }
notifications/progress  { progressToken: "…", progress: 2, message: "E1 — 1 call(s), 12k in / 300 out so far" }
notifications/progress  { progressToken: "…", progress: 3, message: "synthesizing the answer" }
notifications/progress  { progressToken: "…", progress: 4, message: "4 calls · 88k in / 2k out · $0.31" }

Spend is reported as it accrues, one cumulative line per model call, then a final total. The complete report also rides the result body (see what a run spent); the notifications are what let a client see a long run getting expensive before it finishes.

Cancelling a call stops the run between tool calls, not in the middle of one: a plan halfway through creating an issue finishes that call and stops before the next. The result comes back flagged, carrying how many steps had run — and what it spent before stopping.

Questions back to the client

A plan can contain an ask step — a value only a person can supply. Over MCP that becomes an elicitation/create request sent back to your client from inside the tools/call that is running the plan:

-> tools/call            { name: "plan_release_check", arguments: { fallback: "beta" } }
<- elicitation/create    { message: "Which channel should this release go to?", requestedSchema: {…} }
-> (client shows a form, user answers)
<- tools/call result     { output: { channel: "nightly", from_human: true } }

It is capability-gated. A client that did not advertise elicitation at initialize time is never sent a request — the ask resolves as unavailable immediately and the plan runs its declared when_unanswered path, which is why a plan written for a terminal still works here. A client that advertises support and then errors or times out is treated the same way; an unanswerable question is a plan-declared condition, not a server failure. decline and cancel both come back to the plan as "declined".

The answer schema is a flat object of primitive fields, which is the protocol’s constraint — graph enforces it when the plan is validated, so it fails as a review comment rather than at runtime on one host.