Version 5 · Updated 3 November 2026

MCP reference

Every MCP tool's arguments, examples and errors; connection errors and limits.

Every tool, its arguments, an example, and the errors you can get. For setting up a client and how sessions work, see MCP for agents.

Conventions#

repo is always "owner/name", for example "alice/invoices".
ref is a branch name (main, feature/export) or a full commit SHA. Where it's optional, it defaults to the repository's default branch.
number is a change number: 7, not "#7".
Results have two parts:
- text (content), as the CLI prints it;
- JSON (structuredContent), with the full data.
Graph node IDs appear in brackets in the text, for example [ts:.|src/greet.ts|greet()]. Pass them to get_node, and cite them when you report findings.
Errors come back as tool results with isError: true and the API's message. Protocol errors are only for the connection problems listed under "Connection errors" below.

Reading repositories#

list_repos#

No arguments. Repositories the token can see.

alice/invoices (private, admin access, 1 open change)
acme/web (public, read access)

get_repo#

repo. The default branch, branches with their SHAs, the repository's active rulesets (each one's name, whether it targets branches or tags, its targets, with the default branch by name, and the rules it applies), and the clone URLs. Disabled rulesets aren't listed. Who can bypass a ruleset isn't shown.

alice/invoices (private, admin access)
Default branch: main
Branches: main 3fb9414e, feature/export 9c1d22a0
Rulesets: Protected branches (branch: main; changes required, required checks: ci, no deletions, no force pushes, agents can't push or merge), Release tags (tag: v*; no updates, no deletions, no force pushes, agents can't push or release)
Clone: https://git.example/alice/invoices.git or ssh://git@git.example/alice/invoices.git

list_files#

repo, optional ref, optional path (a directory; the root if omitted).

dir  src/controllers
file src/index.ts

read_file#

repo, path, optional ref. Returns the file's text.

Files over 256 KB aren't returned. The result gives their size.
Binary files are reported, not returned: logo.png is a binary file (5121 bytes); not shown.

list_commits#

repo, optional ref, optional path, optional limit (1–200, default 30). Newest first: 3fb9414e Rename greet (alice, 2026-10-19T10:02:11Z). With path, only the commits that changed that file (following renames, with as <old path> where it had another name) or anything in that folder.

get_commit#

repo, sha (a commit, branch or tag). The commit's whole message, author, committer and parents, then its diff against its first parent, up to 200 KB.

blame_file#

repo, path, optional ref. Which commit last changed each line, following moves and copies, as runs of lines: L12-18 3fb9414e alice 2026-10-19 Rename greet. Use it to find the commit, and with list_changes the change, that introduced a line. Files up to 1 MB or 20,000 lines; past that, an error says so.

Changes and reviews#

list_changes#

repo, optional status: open (the default), closed, merged or all.

#2 Add farewell (open; farewell → main)

get_change#

repo, number. Branches and status, then:

the commits;
whether it merges cleanly, for each method: which files a merge commit or squash would conflict in, and whether a rebase would (at which commit) or can't (merge commits in the change);
the review's status: queued, running, done or failed.

get_change_diff#

repo, number. The unified diff of the change, up to 200 KB. Anything longer is cut, and the result says so.

get_review#

repo, number, optional wait (seconds, up to 60), optional against (an environment such as production). The graph review, as bscope change review prints it:

#2 Add farewell: review of 1a2b3c4d → 9c1d22a0
1 rule violation, 0 needing review, 0 against the plan; graph 5 → 7 nodes, 2 → 4 edges.
Check branchscope/review: failed: Errors: 1 rule violation (no-db).

Findings
  Breaks no-db
    InvoicesController.Create() writes invoices  src/Billing.Api/Controllers/InvoicesController.cs:20 [dotnet:…#Create(…) → db:billing:public.invoices]

Change map: 1 new, 1 rule hit
  Create(Invoice) (new, function) in Billing.Api › InvoicesController: nothing calls it yet [dotnet:…#Create(…)]
  Create(Invoice) → writes → table invoices [unresolved] — breaks no-db (not allowed)

The JSON has:

findings (deny and review counts);
views: the checks, renames, element names, and the change map and API view documents.
connections: the change's other repositories, as far as the agent can read them; the text lists their breaking, missing and affected findings under Other repositories. Null when it can't be built yet. With against, each other repository is taken at its current successful deployment to that environment, or at its default branch where it has none or that commit has no graph yet (as deployed): the heading reads Other repositories, against production, and From: says for each repository where it was taken from (as deployed to production at 1a2b3c4d (…), or main as of 5e6f7a8b; not deployed to production, so its default branch).

While the review is still being built, the tool waits up to wait seconds for it. If it's still not done, it returns an error, and the session gets a notification when the review finishes:

the review of #2 is queued; this session gets a notification when it finishes (or wait longer)
the review of #2 is running; this session gets a notification when it finishes (or wait longer)

get_conflict_map#

repo, number. The change's conflict map, as bscope change conflicts prints it: what the target branch and the change each did since their merge base, so an agent resolving a conflict knows what the other side meant, not just which lines clash.

#3 Invoices on the web: feature against main
Merge base 1a2b3c4d, main at 5e6f7a8b, this change at 9c0d1e2f.

Both sides touched: 1 element
  total() (function) [ts:.|src/invoices.ts|total()]
    main: edited (1 line) at src/invoices.ts:5
    this change: edited (1 line) at src/invoices.ts:5

Textual conflicts: 1 file
  src/invoices.ts (content)
    base line 7: total() [ts:.|src/invoices.ts|total()]

Semantic conflicts: 1 conflict
  createInvoice() was renamed to issueInvoice() on main, and this change adds a use of it [ts:.|src/invoices.ts|createInvoice()]
    newInvoice() calls it at src/web.ts:4 [ts:.|src/web.ts|newInvoice()]

The JSON has status, the commits, the conflicts document, both sides' maps and names. Until the target has moved past the merge base, status is none; while the map is being computed, it's queued or running.

list_comments#

repo, number. The change's discussion, oldest first: comments, replies (with the comment they answer), and agents' status updates. These are people's and agents' own words, not derived from the code.

#12 alice: Which date format should the export use?
#13 (reply to #12) alice via claude-code: ISO 8601, as the API does.
#14 alice via claude-code [working]: Adding ISO dates

get_linked_issues#

repo, number. The Linear issues linked to the change (their keys in its branch, title, description or commits, or linked by hand), so an agent can read its task: each one's key, title, status, assignee, link and description. The issues' contents are for members of the organization; anyone else gets the keys only. They're people's words in Linear, not derived from the code. An issue moved to another team shows its key now, as OPS-45, was ENG-123, and one deleted in Linear says so.

ENG-1: Export invoices [In Progress], assigned to Ada https://linear.app/acme/issue/ENG-1

Acceptance: a CSV with every invoice.

With no Linear workspace connected to the repository's organization, it says so.

The code graph#

Graphs are built for protected branches and for changes. A branch nobody has opened a change for may have none.

graph_status#

repo, ref. For example:

main (3fb9414e): graph done
… graph running
… no graph yet

find_nodes#

repo, ref, query (case-insensitive; matched against the name, ID and file path), optional kind (function, type, field, endpoint, channel, route…), optional limit (1–200, default 50).

1 match in 3fb9414e
function greet  src/greet.ts:1 [ts:.|src/greet.ts|greet()]

get_node#

repo, ref, id. The node and its edges, both ways, at most 200 each:

outgoing: what it calls, uses, contains or handles;
incoming: what calls or uses it.

function greet [ts:.|src/greet.ts|greet()]
src/greet.ts:1
Outgoing (0):
Incoming (1):
  main → calls  src/main.ts:2 [ts:.|src/main.ts|main()]

Edges that aren't fully resolved say so, for example (heuristic).

get_view#

repo, ref, view (architecture or data-flow), optional project (architecture: zoom into one project).

Text: every diagram, as the web app's "As text" shows it.
JSON: the view document.

Making changes#

These need a token with write access to the repository. They're logged in activity whether they succeed or are refused.

open_change#

repo, title (up to 200 characters), source (a pushed branch), optional target (the default branch if omitted), optional description.

Opened #3 Add export (open; export → main). The review is queued; get_review shows it when it's done.

rerun_review#

repo, number. Queues the review again: The review of #3 is queued.

close_change, reopen_change#

repo, number.

Closed #3 Add export (closed; export → main).
Closing a closed change gives change is closed.

merge_change#

repo, number, optional method (merge, squash or rebase; the repository's default if left out), optional message (a merge commit's or squash's; the default otherwise). The push guard decides, as for any merge. Into a protected branch, the repository's required checks must have passed first: required checks haven't passed: CI / test.

Into a protected branch, agents are refused, for example main is a protected branch: agents can't update it (release-bot, acting for alice). Push another branch and open a change; a person merges it.
A merge with conflicts is refused with merge has conflicts; a rebase with rebase has conflicts at commit 3fb9414e5c2a, or this change contains merge commits: squash it or use a merge commit.
A method the repository doesn't allow is refused: this repository doesn't allow rebase merges; it allows merge, squash.

add_comment#

repo, number, body (Markdown, up to 20,000 characters), optional replyTo (a comment's ID; replies are one level deep). Commented on #3 (comment #15). The person or agent who wrote the comment you reply to is notified.

post_status#

repo, number, status (working, pushed, blocked or done), text (a line, up to 280 characters). For agents: the latest status shows at the top of the change. #3: blocked: Which date format? A person's credentials get status updates are for agents; people comment.

Tasks#

For agent apps installed in an organization: the work people handed them. A session hears of a new or cancelled task as a notification.

list_tasks#

No arguments. Your open tasks (queued, working or blocked), newest first:

Task 7 in acme/web on #3 (queued, from alice): Address the review findings
Task 6 in acme/web from main (working, from bob): Add an export endpoint for invoices

get_task#

id. One task, in the same form.

update_task#

id, status (working, blocked, done or failed), optional text (a line), optional change (the change you opened for a free-standing task). Task 6: done: Opened #9. On a change, the status also shows on the change. A cancelled or finished task gives the task is cancelled, and another agent's task gives only the agent the task is for reports on it.

Checks#

A change's checks are those of its latest commit: Branchscope's own workflow jobs, and checks reported by apps. See Branchscope actions.

list_checks#

repo, number. The checks, which are required, and where the change stands:

CI / test: failed (required) (test failed (exit 1))
lint: passed
security: not reported yet (required)
Required checks failed: CI / test.

The last line is one of No checks are required., The required checks passed., Required checks are still running or missing. or Required checks failed: …. Calling it also asks for a notification when the checks finish.

wait_checks#

repo, number, optional wait (seconds, 0 to 60, default 60). Waits while checks are queued or running, then answers as list_checks. If time runs out first, it shows them as they are, and the session is still told when they finish.

get_check_log#

repo, number, check (its name, such as "CI / test"), optional step (a step's name, as the log shows it after ▶), optional lines (1 to 2000, default 200). The last lines of the job's log, or the whole of one step's:

CI / test: failed (test failed (exit 1)); the last 4 of 31 lines

 ✗ export/csv.test.ts > handles empty rows
   AssertionError: expected '' to equal 'id,total'

test failed (exit 1)

For a check an app reported, Branchscope has no log: it says so, with the check's details link.

rerun_checks#

repo, number, optional all (default false). Runs the change's workflows that failed or were cancelled again, at its latest commit: Started again: CI (run 41). wait_checks waits for them. With all, it reruns the ones that passed too. Checks reported by apps can't be rerun from here.

Releases and deployments#

Reading needs read access. See Releases and Deployments.

list_releases#

repo. The repository's releases, drafts first (with write access), then newest first:

v1.5.0 v1.5.0 (draft; 9c1d22a0)
v1.4.0 Invoice export (latest; 3fb9414e)
v1.4.0-rc.1 v1.4.0-rc.1 (published, pre-release; 1a2b3c4d)

get_release#

repo, tag. The release, what it compares with and whether its change map is ready (queued, running, done, failed, or none), then its notes:

v1.4.0 Invoice export (latest; 3fb9414e)
Since v1.3.0; change map: done

## What's changed since v1.3.0

- Add invoice export (#12) by @alice with claude-code

create_release#

repo, tag (an existing tag, or a new name), optional target (for a new tag: the branch or commit to make it at), optional title (the tag if left out), optional notes (Markdown; offered from the changes merged since the latest release if left out), optional prerelease. It needs write access, and always makes a draft: nothing is written to git, and a person publishes it, which makes the tag.

Drafted v1.5.0 v1.5.0 (draft; 9c1d22a0). A person publishes it from the release's page.

v1.5.0 already has a release
there's no tag v1.5.0: give a branch or commit (target) to make it at
the tag v1.5.0 already exists at another commit

list_deployments#

repo, optional environment. Each environment with what's running there now (its latest successful deployment) and whether it only takes protected tags, then the 20 most recent deployments, newest first:

production (only from protected tags matching v*): running v1.4.0 (3fb9414e), deployment #12
staging: running main (9c1d22a0), deployment #13

Recent deployments:
#13 staging: succeeded, main (9c1d22a0) by alice, 2026-10-20T12:30:00.000Z
#12 production: succeeded, v1.4.0 (3fb9414e) by alice, 2026-10-20T12:00:00.000Z, https://example.com

get_deployment#

repo, id. One deployment, the run and job it came from (if a workflow made it), and its status history:

#12 production: succeeded, v1.4.0 (3fb9414e) by alice, 2026-10-20T12:00:00.000Z, https://example.com
From run #41 (.branchscope/workflows/release.yml, job deploy)

2026-10-20T12:00:00.000Z queued
2026-10-20T12:00:05.000Z in_progress
2026-10-20T12:01:40.000Z succeeded

Both are read only. Deployments are recorded by workflow jobs with environment:, and by tokens and apps with deployments:write.

Checking a push#

check_push#

repo, branch, optional kind: push (the default; a fast-forward or a new branch), force-push or delete.

First it checks the token's own access; then it asks the push guard. Nothing is pushed.

Result	Meaning
`Allowed: push to export in alice/invoices.`	A real push would go through.
`Not allowed: push to main in alice/invoices. main is a protected branch: agents can't update it.`	The guard's own reason.
`Not allowed: … This token can't write to the repository (read-only, or read access only).`	The token itself can't push (`by: "access"` in the JSON).
`Not allowed: … The push guard can't be reached, so every push is rejected right now (it fails closed).`	`unavailable: true` in the JSON.

Resources#

URI	Contents
`branchscope://{owner}/{repo}/graph/{ref}`	The canonical graph JSON of a branch or commit. URL-encode branch names that contain slashes: `branchscope://alice/invoices/graph/feature%2Fexport`.
`branchscope://{owner}/{repo}/changes/{number}/review`	The change's review, as `get_review`'s JSON `views`.

Errors from tools#

Message	Why	What to do
`repository not found`	It doesn't exist, or this token can't see it (private repositories aren't revealed).	Check the name, and the token's repository list.
`you need write access to this repository`	A write tool with a read-only token, or read-only access.	Use a token with write scope.
`no branch or commit <ref>`	The ref doesn't exist.	Push it, or check the name.
`the repository is empty`	No branches yet.	Push first.
`no graph for <sha> yet (the build is running); graph_status shows its progress`	The graph is being built, or was never built for this ref.	Wait, or open a change so its head gets a graph.
`the graph for <sha> is no longer stored; rebuild it`	Old graphs are cleaned up.	Rebuild the graph from the web app's graph page, or the API (`POST …/graphs`).
`#<n> has no graph review`	The change has no review yet.	`rerun_review`.
`the review of #<n> failed: …`	The indexer couldn't review it; the reason follows.	Fix the cause, then `rerun_review`.
`change not found`, `change is closed`, `change is merged`	Wrong number, or the wrong state for the action.	`list_changes`.
`no node <id> in <sha>`	The ID isn't in that commit's graph.	`find_nodes` on the same ref.
`#<n> has no check named <name>; list_checks shows them`	Wrong check name, or it ran on an older commit.	`list_checks`.
`required checks haven't passed: …`	`merge_change` into a protected branch before the required checks passed.	`wait_checks`, then fix what failed.

Connection errors#

These are HTTP errors on /v1/mcp, before any tool runs.

Status	Message	Meaning
401	`invalid or expired token`, or `sign in through OAuth …`	No token, or one that's revoked or expired. The response's `WWW-Authenticate` header points the client to Branchscope's sign-in.
403	`MCP is for agents: …`	A personal token or a web session.
400	`no session: send an initialize request first`	A request without a session that isn't `initialize`.
404	`session not found; start a new one`	The session expired (30 minutes idle), the control plane restarted, the organization paused its agent, or it belongs to another credential. Clients reconnect on their own.
429	`this token already has 10 open sessions …`	Close a session (`DELETE /v1/mcp`), or wait for one to expire.

Limits#


Sessions per authorization or installation	10
`get_review` wait	60 seconds
Idle session lifetime	30 minutes
`read_file`	256 KB
`get_change_diff`	200 KB
`get_commit` diff	200 KB
`blame_file`	Files up to 1 MB or 20,000 lines
`find_nodes` results	200 (default 50)
`get_node` edges	200 each way
`list_commits`	200 (default 30)