Graphite MCP server: two tools, one runs commands

Two tools. One of them runs any gt command. Its description tells the agent to stop using git commit.

Last verified 27 August 2026 · from The Graphite CLI on npm and the server's own tools/list response

This page is one of 90 in a directory of monitoring and developer tools. Each page checks what an AI coding agent can get out of the tool through its MCP server, the connector that lets the agent query the tool directly.

What is the Graphite MCP server?

It is Graphite's server for the Model Context Protocol. Graphite is a stacked pull-request workflow: each branch sits on top of the one below it, and gt submit opens a pull request for each branch in the stack. The server exposes that workflow through the CLI rather than through an API.

run_gt_cmd requires three arguments. args is an array passed straight to gt. cwd is an absolute project path. why is a one-line explanation of the command. That last field is unusual and exists to make the agent state intent.

learn_gt carries a 44-character description. The tool returns an explanation of stacking. It is documentation, not an operation.

Graphite brings stacked pull-request work into the agent's code-review view. Its release connection stops at opening the pull request; the product has no wider runtime or cost surface here.

In practice, Graphite changes how work is committed rather than answering questions about it. The connector is a way to act, not a way to read. Nothing here reports on a build, a service or a cost, so every other stage needs its own connector.

What can an AI agent do with Graphite?

Every row that works uses the same tool. There is no schema-discovery call here: run_gt_cmd takes an argument array, so the agent has to know the gt subcommand before it calls anything. An allowlist that approves run_gt_cmd approves every gt subcommand at once, including submission.

What connecting costs before the first question

A context window is the amount of text a model can hold at once, and connecting uses some of it before the agent asks anything. Every tool the server registers sends its name, description and input schema to the model when the session starts. The tool list is charged whether or not a single tool is called.

2 tools cost between 954 and 1,770 tokens. BuildPulse registers five tools and costs less. Tool count is not context cost.

Descriptions average 1,561 characters across the two, and run_gt_cmd carries 3,077 of them. The schemas are small at 307 characters, because one array and two strings is the whole interface.

Encodings: GPT-5.6, GPT-5.5 o200k_base; GPT-4, GPT-3.5 cl100k_base; Claude Haiku 4.5 to Opus 5 count_tokens. Counted 24 August 2026 from tools/list on the released CLI 1.8.6 from npm. It was started with gt mcp locally.

Registration is static, so no Graphite account was involved. Figures cover name, description and input schema. The two models in column one share the o200k_base encoding, so they get one count. The spread is formatting, about 10%. Reasoning tokens are output, spent per request. This count is input, charged once at connection.

The Claude figures are measured rather than encoded. Anthropic publishes no local tokenizer. The definitions were sent to the API's count_tokens endpoint, and a no-tools baseline was subtracted. The range covers two tokenizer generations rather than two serializations. Haiku 4.5 and Opus 4.6 sit at the low end. Opus 5 and Sonnet 5 sit at the high end. The gap between them is about a tenth.

Graphite MCP server limits: where answers come back incomplete

Two limits follow below. One comes from one tool standing in for an entire command line. The other comes from that tool's description.

How to configure Graphite MCP for agents

1. 1

   Treat run_gt_cmd as shell access to gt

   It accepts any argument array, so approving it once approves every subcommand, including submission.

2. 2

   Read the description before connecting

   It instructs the agent to assume a stack of pull requests and to stop using git commit and git push.

3. 3

   Set the working directory deliberately

   cwd is required and must be absolute, which means the agent names the repository it acts on.

4. 4

   Expect the why field to be the audit trail

   The tool requires a one-line reason for every command, which is the only record of intent the interface provides.

Paste this into your agent’s instructions

One tool covers every operation, so the tool name in a transcript says nothing about what happened. The block makes the agent name the command.

When you answer using Graphite MCP tools, state:
- The exact gt command you ran, including every argument.
- The absolute working directory it ran in.
- Whether the command pushed or opened a pull request.
  gt submit --no-interactive does both without prompting.
Never state that data does not exist. State that the command
above produced no output.
Write your answer in ASD-STE100 Simplified Technical
English. Use short sentences with one idea in each.

Do you need the MCP server at all?

Not when a person is deciding the structure. Graphite's gt command is the direct alternative, and in a terminal it performs the same work while a person decides each step.

The connector earns its place when the agent is writing the code as well as committing it, because the stack structure can then follow the work rather than be reconstructed afterwards.

For reading pull requests, reviews and CI status, a repository connector answers questions this one cannot, since nothing here queries an API.

Connect it when the agent is authoring stacked changes. Use the terminal when a person is deciding the structure.

Graphite MCP server setup

There is no separate package. Installing the Graphite CLI installs the server, and gt mcp starts it.

Authentication is the CLI's own stored session, so a machine where gt auth has already run needs no credential in the configuration.

claude mcp add-json "graphite" '{"command":"npx",
  "args":["-y","@withgraphite/graphite-cli","mcp"]}'

{"mcpServers":{"graphite":{"command":"npx",
  "args":["-y","@withgraphite/graphite-cli","mcp"]}}}

[mcp_servers.graphite]
command = "npx"
args = ["-y", "@withgraphite/graphite-cli", "mcp"]

Every other client

Each block below is the configuration for one client, with the file path and the key that client expects.

{"mcpServers":{"graphite":{"command":"npx",
  "args":["-y","@withgraphite/graphite-cli","mcp"]}}}

{"mcpServers":{"graphite":{"command":"npx",
  "args":["-y","@withgraphite/graphite-cli","mcp"]}}}

{"servers":{"graphite":{"command":"npx",
  "args":["-y","@withgraphite/graphite-cli","mcp"]}}}

{"mcpServers":{"graphite":{"command":"npx",
  "args":["-y","@withgraphite/graphite-cli","mcp"]}}}

{"mcpServers":{"graphite":{"command":"gt",
  "args":["mcp"]}}}

Read-only access, permissions and security

• One tool executes commands

  run_gt_cmd passes an argument array to gt, so its reach is whatever the CLI can do in the given directory.

• Submission is one of those commands

  The tool's own description directs the agent to gt submit --no-interactive, which pushes branches and opens pull requests without a prompt.

• The description is instruction, not documentation

  It tells the model to assume stacked pull requests and to avoid git commit and git push, which changes behavior beyond this connector.

• Client approval is all-or-nothing

  There is no second tool to approve separately, so an allowlist cannot separate a restack from a submission.

Troubleshooting

A command fails with a path error

cwd is required and must be an absolute path to the project root. A relative path is rejected by the schema.

The agent stopped using git commit

That is the tool description working as written. It instructs the model to use gt create instead of git commit and gt submit --no-interactive instead of git push.

A pull request was opened unexpectedly

gt submit --no-interactive submits the current branch and everything below it in the stack. It is reachable through the same tool as every other command.

Authentication is missing

The server uses the CLI's stored session. Run gt auth in a terminal; nothing in the MCP configuration carries a credential.

Graphite MCP server: Reference

What engineers report

There is no public repository for the CLI, so the package and the wire capture are the only primary sources.

npm facts retrieved 24 August 2026. A GitHub lookup for a withgraphite/graphite-cli repository returned not found on the same date, so no repository facts are claimed. Tool counts and description sizes come from the released CLI's own tools/list response.

Should you connect an agent to Graphite?

Yes. Best for repositories where stacked pull requests are the agreed workflow, since the description enforces that assumption.

Strongest fit

Teams already on Graphite whose agents write code and are expected to structure it as a stack.

Main advantage

The whole gt command line is reachable in one call, with a required reason field on every command.

Main weakness

One tool covers every operation, so a client allowlist cannot separate reading from submitting.

Operational risk

gt submit --no-interactive pushes branches and opens pull requests, and the tool's own description directs the agent to it.

Frequently asked questions