MCP for agents

Branchscope runs an MCP (Model Context Protocol) server, so agents such as Claude Code can use repositories, changes, reviews, discussions, tasks and code graphs as tools. They don't need to go through the web app or parse CLI output. Pushing still happens with git, and the push guard still checks every push and merge.

Connecting#

The endpoint is the API's /v1/mcp (Streamable HTTP). GET /.well-known/branchscope on the web app names it (mcp).

Add the server to the agent. For Claude Code:

claude mcp add --transport http branchscope https://<api host>/v1/mcp

The client signs in through OAuth on its own: it finds Branchscope's sign-in, registers itself and opens a consent page in your browser. Approve it there, choosing the repositories it may use. See OAuth apps.

Clients that take a header instead use a token from the CLI: bscope agent login --name claude-code once, then Authorization: Bearer $(bscope agent token --name claude-code). Those tokens last an hour.

Only agents can connect: OAuth apps (the Branchscope CLI's agents among them) and agent apps installed in an organization. Personal tokens and web sessions are refused. That way the agent is always named, and always acting for a person or an organization that chose to let it.

Sessions#

• A session belongs to the authorization (or the installation) that opened it. No other credential can use it.
• Sessions end after 30 minutes without a request.
• A token can have at most 10 sessions open.
• Revoking or expiring the token stops its sessions at their next request.

Tools#

The MCP reference has every tool's arguments, examples and error messages.

Every tool runs with the token's own access, exactly as the API does:

• read-only tokens can't write;
• tokens limited to some repositories don't see the others;
• private repositories you can't read are "not found".

Results come as readable text, written as the CLI prints them, plus the same data as JSON (structured content). Graph node IDs appear in brackets, so an agent can look an element up and cite it.

Reading#

Tool	What it returns
list_repos	Repositories the token can see
get_repo	Default branch, branches, the repository's active rulesets (each one's name, kind, targets and rules), clone URLs
list_files	A directory at a branch or commit
read_file	A text file (up to 256 KB; binary files are reported, not returned)
list_commits	Recent commits, or with path a file's or folder's history
get_commit	One commit: its message, author, committer, parents and diff
blame_file	Which commit last changed each line of a file
list_changes	Changes, by status
get_change	A change: commits, whether each merge method would merge cleanly, its review's status, its checks
get_change_diff	The text diff (up to 200 KB)
get_review	The graph review: rule findings with file and line, the plan check, renames, the other repositories it breaks or affects, and the change map and API diagrams. With wait (up to 60 seconds) it waits for a review that's still running. With against (an environment) it compares the other repositories as deployed there.
get_conflict_map	A change's conflict map against its target: what each side did to the elements both touched, the conflicting files with the elements in each region, and semantic conflicts that merge cleanly as text but don't fit together
list_comments	A change's discussion: comments, replies and agents' status updates
get_linked_issues	The Linear issues linked to a change: each one's title, status, assignee, link and description, for members of the organization
list_checks	A change's checks, and whether the required ones passed
wait_checks	Waits up to 60 seconds for a change's checks to finish, then shows them
get_check_log	The log of one of a change's workflow checks: its last lines, or one step's
list_tasks, get_task	Your open tasks, as an agent app installed in an organization
graph_status	Whether a ref's graph is built
find_nodes	Search a ref's graph by name, ID or path
get_node	A node and its incoming and outgoing edges
get_view	The architecture or personal-data-flow view of a ref
list_releases, get_release	A repository's releases; one release, its notes and whether its change map is ready
list_deployments, get_deployment	Environments and what's running in each, recent deployments; one deployment and its history
check_push	Would a push, force push or delete to a branch be allowed?

check_push checks the token's access, then asks the push guard exactly as a real push would. Nothing is pushed. If the guard can't be reached, the answer is "not allowed": a real push would be rejected too.

Changing things#

Tool	Does
open_change	Opens a change from a pushed branch (into the default branch unless you say otherwise)
rerun_review	Runs the review again
rerun_checks	Runs a change's failed workflows again (or all of them)
close_change, reopen_change	Closes or reopens a change
merge_change	Merges as a merge commit, a squash or a rebase, if the push guard allows it
add_comment	Comments on a change, or replies to a comment
post_status	Says what you're doing on a change: working, pushed, blocked or done, with a line
update_task	Reports on a task: working, blocked, done or failed; links the change you opened for it
create_release	Drafts a release of a tag; a person publishes it

These follow the API's rules. In particular, agents can't update a branch whose rulesets block agents, such as main, by push or by merge, and they only draft releases. A change into main waits for a person to merge it, and merge_change returns the guard's refusal.

Notifications#

Branchscope tells a session, as MCP log messages, when:

• a task is handed to it, or cancelled (agent apps);
• a review it asked about with get_review finishes;
• someone replies to a comment it wrote;
• a check finishes on a change it opened, or one it asked about with list_checks or wait_checks.

So an agent doesn't poll: it gets on with something else and picks the work up when it hears.

Resources#

For clients that attach context:

• branchscope://{owner}/{repo}/graph/{ref}: a branch's or commit's graph JSON. URL-encode branch names that contain slashes.
• branchscope://{owner}/{repo}/changes/{number}/review: a change's review: checks, renames and views.

What's logged#

Activity → Agents (MCP) shows:

• each session starting;
• every change an agent tried to make, whether it succeeded or was refused (by access, the guard or the change's state), and why.

Reads aren't logged. Sessions are visible to the agent's person and site administrators. Writes are visible to anyone who can read the repository.

A typical loop#