GT MCP is a Model Context Protocol server built into the Graphite CLI (gt mcp) that lets AI agents in tools like Cursor and Claude Code automatically break large changes into smaller, reviewable stacked pull requests. It is a local MCP server over the CLI, not a remote HTTP API.
openapi: 3.0.1
info:
title: Graphite Platform
description: >-
Graphite does not publish a standalone public REST API. Graphite is built on
top of GitHub: it installs as a GitHub App (graphite-app) that consumes GitHub
webhooks and calls GitHub's APIs with short-lived tokens, and it is driven by
the gt CLI which authenticates with a Graphite auth token. This OpenAPI models
the real, observable surface area as logical operations: the GitHub App
install entry point and the documented gt CLI stacked-PR workflow operations.
Endpoint paths for CLI operations are illustrative of the platform actions the
CLI performs and are not a documented public HTTP contract.
termsOfService: https://graphite.dev/terms
contact:
name: Graphite Support
url: https://graphite.com/docs/feature-requests-bugs
version: '1.0'
servers:
- url: https://app.graphite.dev
description: Graphite hosted platform (driven by the gt CLI and web app)
- url: https://github.com
description: GitHub App install and marketplace entry points (GitHub-mediated)
tags:
- name: GitHub App
description: GitHub App install and webhook integration entry points.
- name: Authentication
description: Graphite CLI authentication with a Graphite auth token.
- name: Stacks
description: Create, submit, sync, and merge stacked pull requests via the gt CLI.
- name: Merge Queue
description: Graphite merge queue actions.
paths:
/apps/graphite-app:
get:
operationId: installGitHubApp
tags:
- GitHub App
summary: Install the Graphite GitHub App
description: >-
Entry point to install the Graphite GitHub App on an organization. The
installed app receives GitHub webhooks for CI status, mergeability, and
push events and calls GitHub's APIs with fine-grained permissions and
short-lived tokens. Served by GitHub, not by Graphite.
responses:
'200':
description: GitHub App installation page.
/marketplace/graphite-dev:
get:
operationId: getMarketplaceListing
tags:
- GitHub App
summary: Graphite GitHub Marketplace listing
description: >-
The Graphite listing on the GitHub Marketplace, from which an
organization owner can install the app. Served by GitHub.
responses:
'200':
description: GitHub Marketplace listing page.
/auth:
post:
operationId: authenticateCli
tags:
- Authentication
summary: Authenticate the gt CLI
description: >-
Logical representation of `gt auth`, which registers a Graphite auth
token so the CLI can create and update pull requests on the user's
behalf. The token is obtained from the Graphite web app.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AuthRequest'
responses:
'200':
description: CLI authenticated.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResult'
'401':
description: Invalid or expired auth token.
/stacks/branches:
post:
operationId: createBranch
tags:
- Stacks
summary: Create a stacked branch
description: >-
Logical representation of `gt create`: create a new branch stacked on
the current branch with committed changes.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBranchRequest'
responses:
'201':
description: Stacked branch created.
content:
application/json:
schema:
$ref: '#/components/schemas/Branch'
/stacks/submit:
post:
operationId: submitStack
tags:
- Stacks
summary: Submit a stack to GitHub
description: >-
Logical representation of `gt submit`: push stacked branches to GitHub
and create or update their pull requests.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitRequest'
responses:
'200':
description: Pull requests created or updated.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PullRequest'
/stacks/sync:
post:
operationId: syncStack
tags:
- Stacks
summary: Sync branches with remote
description: >-
Logical representation of `gt sync`: pull from remote, delete merged
PRs, and restack local branches.
responses:
'200':
description: Local stack synced with remote.
content:
application/json:
schema:
$ref: '#/components/schemas/SyncResult'
/stacks/merge:
post:
operationId: mergeStack
tags:
- Merge Queue
summary: Merge a stack of pull requests
description: >-
Logical representation of `gt merge`: merge pull requests from trunk
through the current branch via Graphite, optionally through the merge
queue.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MergeRequest'
responses:
'200':
description: Stack merged or enqueued in the merge queue.
content:
application/json:
schema:
$ref: '#/components/schemas/MergeResult'
components:
securitySchemes:
graphiteAuthToken:
type: http
scheme: bearer
description: >-
Graphite auth token registered via `gt auth`, used by the CLI to act on
the user's behalf.
schemas:
AuthRequest:
type: object
properties:
token:
type: string
description: Graphite auth token copied from the web app.
required:
- token
AuthResult:
type: object
properties:
authenticated:
type: boolean
user:
type: string
Branch:
type: object
properties:
name:
type: string
parent:
type: string
description: Parent branch in the stack.
trunk:
type: boolean
CreateBranchRequest:
type: object
properties:
name:
type: string
message:
type: string
description: Commit message for the new branch.
all:
type: boolean
description: Stage all changes before committing.
required:
- name
SubmitRequest:
type: object
properties:
stack:
type: boolean
description: Submit the entire stack rather than only the current branch.
draft:
type: boolean
publish:
type: boolean
PullRequest:
type: object
properties:
number:
type: integer
title:
type: string
branch:
type: string
url:
type: string
format: uri
state:
type: string
enum:
- draft
- open
- merged
- closed
SyncResult:
type: object
properties:
restacked:
type: array
items:
type: string
deleted:
type: array
items:
type: string
MergeRequest:
type: object
properties:
useMergeQueue:
type: boolean
description: Route the merge through the Graphite merge queue.
MergeResult:
type: object
properties:
merged:
type: array
items:
type: string
enqueued:
type: boolean
security:
- graphiteAuthToken: []