graph as an MCP server

Serving your plans and the plan authoring commands to another agent

graph is an MCP client — that’s MCP servers. This page is the other direction: graph mcp serve exposes your plans to somebody else’s agent, over stdio.

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

The point is not to give an agent another shell. 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.

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

Two populations, deliberately named apart.

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 commands

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.

graph_tools_list and graph_tools_show return the complete vocabulary a step’s tool field may name: the namespaced tools and the seven control steps under the (control) source. That matters more over MCP than on a terminal — the server does not serve graph’s documentation, so an agent that cannot get exit’s or ask’s schema from graph_tools_show has nowhere to look but graph’s source.

These are the plan authoring CLI, one tool per verb, so an agent can 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.

The graph_ prefix is what keeps a plan named tools_list from colliding with the verb of the same name.

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

How outcomes come back

The CLI signals with exit codes. Those have nowhere to go over MCP, so the distinctions they carry survive as data instead.

Situation	CLI	Over MCP
Plan ran	exit 0	result: {answer, output, plan, steps_executed, exit}
Plan needs inputs	exit 3	isError, body carries inputSchema and problems — retry with the argument
Exit gate asserted	exit 4	isError, body carries the gate’s message and step
Edit refused	exit 1	isError, body carries problemsIntroduced
Unknown tool, bad argument type	exit 1	a JSON-RPC error — this one is the caller’s mistake, not a result

The distinction in that last row is the important one. A refused edit is an answer: the problem list is what the agent needs to fix its next attempt, and flattening it into an error string would leave the model parsing prose to recover it. A misspelled tool name is not an answer at all.

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: "synthesizing the answer" }

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.

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.

Notes and limits

• Tool activity also goes to stderr, where MCP clients conventionally collect server logs.
• ask and chat are not served. They are graph’s conversational layer; an agent calling graph does not need another agent, it needs the plans.
• Do not point graph’s own [mcp] config at graph mcp serve. The pipeline’s cycle detection and depth cap work within a process; they do not cross a process boundary.
• Plan writes are serialized, so concurrent authoring calls cannot silently lose an edit.