MCP tools
Branches
MCP tools for creating, inspecting, syncing, previewing, and deleting docs branches from a connected agent
Branches
Branch tools let a connected agent work on docs changes in a named branch instead of main. An agent can create a branch, check its status and diff, build a preview, and delete it when it is no longer needed. Publishing is a separate set of tools, described in Publish and history.
Writes to main are rejected through MCP. Start every docs change on a branch.
Branch tools
| Tool | What the agent can do | Scope |
|---|---|---|
list_branches | List the branches of a project | docs:read |
create_branch | Create a named branch to hold working changes | docs:write |
get_branch_status | Check the state of a branch | docs:read |
get_branch_diff | Review the changes a branch contains | docs:read |
sync_branch | Bring a branch up to date | Not named in the scope reference |
build_preview | Build a preview of a branch | docs:write |
delete_branch | Delete a branch that is no longer needed | Not named in the scope reference |
Each tool checks the scopes granted to the connected agent. A tool call that needs a scope the agent does not have fails. For what each scope allows, see MCP scopes and approval requests.
Note:
The scope reference names docs:read and docs:write for branch reads and writes, but it does not name a scope for sync_branch or delete_branch. Check the scopes on the consent page when you connect the agent, and review them under Settings, Connected agents.
Typical branch workflow
Ask your agent to make a change on a branch, then have it build a preview and review the diff before publishing. The agent uses these tools in order.
Create a branch
Ask the agent to create a named branch for the change, for example "Create a branch called api-auth-update for this project." The agent calls create_branch.
Edit pages on the branch
The agent edits pages on the branch with write_page or edit_docs. Those tools are described in Docs pages.
Build a preview
Ask the agent to build a preview of the branch. The agent calls build_preview, and you can open the preview to check the rendered pages.
Review the branch diff
Ask the agent to show the diff. It calls get_branch_diff and summarizes the changed pages. Use get_branch_status to check where the branch stands.
Publish the branch
When the changes look right, ask the agent to publish the branch. Publishing is described in Publish and history and requires the publish scope.
Example prompts
"List the branches for my docs project."
"Create a branch named pricing-page and update the pricing page on it."
"Check the status of the pricing-page branch and show me its diff."
"Build a preview of pricing-page."
"Delete the pricing-page branch. I have already published it."
Related pages
Docs pages: read, write, and search pages on a branch.
Publish and history: publish a branch and restore earlier publications.
Site settings: change site settings on a branch.
MCP scopes and approval requests: what each scope allows.
Branches, previews, publishing, and restore: the same workflow in the dashboard.