MCP Tools, Resources and Prompts¶

This page is generated from the server's registries by task docs:export-mcp-tools. Do not edit manually.

bb ai mcp serve registers 27 tools. It exposes the 19 that only read, and with --allow-writes every one, unless --tools, --exclude or a scope withholds it. On a server started with --elicitation-opt-in, 6 ask the person to confirm a call in the MCP client before they run.

The MCP server guide wires it into a client, with examples of the views show puts in front of you.

The tools answer the agent, and show is for the person: an agent uses the tools to find, read and change things, and show for someone who is there to see the result, never when it works on its own. Tools and views says which for what.

refresh_view and suggest_form_values are for those views: MCP Apps offers them to views and not to the model, and they go with show whether or not --tools names them. A click in a view is a call of a tool, through the client, never a connection to Bitbucket (how views work).

Tool	What it does	Access	Asks
`add_pr_comment`	Comment on pull request	writes	never
`compare_refs`	Compare refs	read-only	never
`create_pull_request`	Create pull request	writes	never
`create_tag`	Create tag	writes	always
`disable_auto_merge`	Disable auto-merge	writes	always
`enable_auto_merge`	Enable auto-merge	writes	always
`get_build_status`	Get build status	read-only	never
`get_commit`	Get commit	read-only	never
`get_file_content`	Read file	read-only	never
`get_pr_diff`	Get pull request diff	read-only	never
`get_pull_request`	Get pull request	read-only	never
`get_repository_clone_info`	Get clone URLs	read-only	never
`list_branches`	List branches	read-only	never
`list_commits`	List commits	read-only	never
`list_pr_comments`	List pull request comments	read-only	never
`list_pull_requests`	List pull requests	read-only	never
`list_required_builds`	List required builds	read-only	never
`list_tags`	List tags	read-only	never
`merge_pull_request`	Merge pull request	writes	always
`prepare_pr_review`	Prepare a review	read-only	never
`refresh_view`	Refresh a view	read-only	never
`resolve_ref`	Resolve ref	read-only	never
`search_repositories`	Search repositories	read-only	never
`set_build_status`	Set build status	writes	always
`show`	Show a view	read-only	never
`suggest_form_values`	Suggest form values	read-only	never
`update_pull_request`	Update pull request	writes	when-setting-draft

What each tool tells the model

The description a client hands the model with each tool, as the server sends it.

add_pr_comment: Add a comment to the person's review of a pull request. It stays pending, seen only by the person, until they publish the review in Bitbucket with Finish review; prepare_pr_review says where. Provide path and line to create an inline comment on a specific file line. Provide parent_id to reply to an existing comment. bb ends the text with a line saying an AI agent wrote it for the person; do not add one yourself.
compare_refs: List the commits reachable from 'from' but not from 'to': what one ref has that the other lacks. For the commits a feature branch adds, pass from=feature and to=main.
create_pull_request: Create a new pull request. When the person asks for one, create it, filling in what they left to you. bb ends the description with a line saying an AI agent wrote it for the person; do not add one yourself.
create_tag: Create a tag on a specific commit or ref. Use for release tagging after a PR is merged.
disable_auto_merge: Disable auto-merge on a pull request. The PR will no longer be merged automatically.
enable_auto_merge: Enable auto-merge on a pull request. The PR will be merged automatically once all required checks pass and reviewers have approved.
get_build_status: Get build/CI statuses for a specific commit. Use this to check whether CI passed before declaring a PR ready to merge.
get_commit: Get details of a specific commit including author, message, and timestamp.
get_file_content: Read a file in a repository. Text comes back as a window of numbered lines: start_line and line_count choose it, and each answer says which lines it holds and where the next window starts. A Word, PowerPoint or Excel file comes back as the text extracted from it, and an archive (zip, jar, tar, tar.gz, tar.bz2) as a listing of its entries, both in the same windows. An image (PNG, JPEG, GIF, WebP, BMP, TIFF) comes back as an image, converted to PNG or JPEG when clients do not take its format, turned upright when its metadata says it was stored turned, and scaled down when it is large, with a note saying which. Audio and video come back as themselves beside a description when they are small, and as the description alone when not. A PDF or any other file is described by its type and size rather than shown, and a file over 64 MiB is described without being read.
get_pr_diff: Get the diff of a pull request as unified diff text.
get_pull_request: Get pull request details including title, state, reviewer approvals, and merge status. The review_summary field reports unresolved comment threads, open tasks and reviewers who requested changes; action_required is true when the pull request is waiting on the author, and is absent when the counts it rests on were not all measured -- read counts_source to see which were.
get_repository_clone_info: Get HTTPS and SSH clone URLs for a repository. Use these URLs with git clone to check out the repository locally.
list_branches: List branches in a repository. Use to discover existing branches before creating a new one or a pull request.
list_commits: List commits in a repository branch. Use to walk history to find a good base or diagnose what changed.
list_pr_comments: List review comment threads on a pull request, unresolved first. Bitbucket models a task as a blocker comment, so this returns reviewer comments and tasks together, each with its resolution state, file anchor and reply count. Use state=open to see only what is still waiting on the author. Without path this returns the aggregate pull request comment view derived from activities.
list_pull_requests: List pull requests. With project and repo, lists that repository's. Without repo, lists your own pull requests across every repository (the dashboard), narrowed to project when one is given.
list_required_builds: List required build checks that must pass before a pull request can be merged. Check this before attempting a merge to understand what CI must succeed.
list_tags: List tags in a repository. Use to find the latest release baseline or versioning information.
merge_pull_request: Merge a pull request. Bitbucket refuses the merge while one of the repository's merge checks fails: each repository sets its own, which may require approvals, passing builds or resolved tasks, or nothing at all. get_pull_request lists what blocks the merge in pull_request.mergeability.blockers.
prepare_pr_review: Hand a review to the person to publish. The comments added with add_pr_comment wait in their draft review; this returns the pull request's URL, how many comments the draft holds, and the status you suggest. Nothing is approved or published here: the person publishes the review in Bitbucket with Finish review, and approves or requests changes. Tell them where it waits and what you suggest.
refresh_view: Called by bb's views, not by the model: reads what a view shows, for a view to open it or to keep current. With since, the fingerprint of the data a view draws, it answers with the data only when that differs.
resolve_ref: Resolve a branch or tag name to its tip commit SHA. Use as a cheap existence check before cloning or creating a pull request.
search_repositories: Search for repositories by name, optionally filtered by project. Returns project key, slug, and display name.
set_build_status: Report a build/CI status for a commit back to Bitbucket. Use this when running CI pipelines that should surface results in PR views.
show: Show the person a pull request, a list of pull requests or a pull request's diff as an interactive view, in clients that display MCP Apps views, or a pull request form for them to finish and submit. It is for the person, not for you: its answer says what was shown, not the data, so read with the other tools. Call it only when a person is there to see it, never when you work on your own, as in a scheduled, background or batch task; and once, after you have what you need and before your answer. Kind pull_request, for a pull request the person asked about or should watch, takes project, repo and id; its view keeps its builds and reviews current, and its overview has its comments and activity. Kind diff takes the same, for changes the person cannot open in their own editor, such as another repository's, and draws the comments on their lines. Kind pull_requests, for what needs the person, takes the filters list_pull_requests takes. Kind pull_request_form is for a person who wants a say in a pull request before it exists, being particular about its description or reviewers or asking to see the draft; for a clear request to open one, call create_pull_request instead. It takes project, repo, from_ref and what you drafted (title, description, to_ref, reviewers, draft), or an id to edit that pull request; nothing is created or changed until the person submits it. In a client that displays no views, it shows nothing and says so.
suggest_form_values: Called by bb's pull request form, not by the model: suggests the repository's branches, or the people who can read it as reviewers, matching what the person typed, and names the default reviewers and code owners for the branches they picked.
update_pull_request: Update a pull request's title, description, or draft state. Use draft=false to mark a draft pull request ready for review. Requires the current version from get_pull_request for optimistic locking; a stale version is rejected rather than overwriting someone else's edit. bb ends a description it sends with a line saying an AI agent wrote it for the person, once; do not add one yourself.

Tools that ask¶

A tool asks when it merges, changes whether or when a pull request merges, or feeds a check that decides whether one may. create_tag asks too, since release pipelines commonly act on a new tag. update_pull_request asks only for a call that sets the draft flag: a draft cannot be merged, and making a pull request a draft cancels its auto-merge.

They ask only on a server started with --elicitation-opt-in, or with mcp_elicitation_opt_in set in your own configuration file or by policy. Everywhere else the client decides whether a call runs. The confirmation is an MCP elicitation. The client shows what the call will do, with one box to tick, and the tool acts only once the person accepts. A client that cannot show a confirmation gets error -32021 (missing required client capability) for those tools, and nothing reaches Bitbucket. Whether a client puts the question to the person or answers it itself is the client's to decide.

Writes¶

bb ai mcp serve exposes only the tools that read unless --allow-writes, or mcp_allow_writes: true in your own configuration file, lets it write, and the read_only policy key keeps it from writing whatever they say. Leave writes off for a client you do not trust to make changes: a client that cannot be trusted with them should not make changes in Bitbucket, so make them yourself.

Resources¶

Pull requests, their diffs and open threads, files and commits are also resources. The person attaches them in the client, and a model in a client that reads resources can read them itself. A resource URI is a name bb resolves with its own credentials, not a link: the client asks bb for it, never Bitbucket, and the scope and the audit trail cover a resource read as they cover a tool call.

Resource	URI template	Served while	What it reads
`pull_request`	`bitbucket://projects/{project}/repos/{repo}/pull-requests/{id}`	`get_pull_request`	A pull request: title, state, branches, author, reviewers and their votes, the review summary and the description, as get_pull_request answers with them.
`pull_request_diff`	`bitbucket://projects/{project}/repos/{repo}/pull-requests/{id}/diff`	`get_pr_diff`	A pull request's changes as a unified diff, up to 128 KiB; a longer diff says where it stops.
`pull_request_threads`	`bitbucket://projects/{project}/repos/{repo}/pull-requests/{id}/threads`	`list_pr_comments`	A pull request's unresolved review comments and tasks, up to 100 threads, as list_pr_comments answers with state=open.
`file`	`bitbucket://projects/{project}/repos/{repo}/files/{+path}{?at}`	`get_file_content`	A file at a branch, tag or commit (the default branch when at is left out), as get_file_content answers with it: text as its first window of numbered lines, a document as its extracted text, an archive as a listing, an image or small audio and video as themselves beside a description, and any other file described.
`commit`	`bitbucket://projects/{project}/repos/{repo}/commits/{id}`	`get_commit`	A commit: its message, author, committer, dates and parents, as get_commit answers with them.

A template is served while the tool it answers like is exposed, so --tools and --exclude decide the resources as they decide the tools: a server that leaves get_file_content out reads no files.

The resource list holds your open pull requests and those waiting on your review, up to 25 of each, while list_pull_requests and get_pull_request are exposed. A client can complete a template's project, repository, pull request, path and ref as the person types.

The results of get_commit, get_file_content, get_pr_diff and get_pull_request link the resource they came from, beside their content, so a client can offer to attach it or read it again.

Prompts¶

A prompt is a request the person picks in the client, often as a slash command, with the content it is about attached. Its arguments complete like a template's, and it is served while every tool whose answer it attaches is exposed.

Prompt	Arguments	Served while	What it does
`review_pull_request`	`project`, `repo`, `id`	`get_pull_request`, `get_pr_diff`, `list_pr_comments`	Review a pull request for defects, risky changes and missing tests, with its details, its diff and its open review threads attached.
`explain_pull_request`	`project`, `repo`, `id`	`get_pull_request`, `get_pr_diff`	Explain what a pull request changes and why, for someone who has not seen it, with its details and its diff attached.

See MCP Server Governance for scoping a server to a project or repository, restricting it with a read-only token, and mandating an audit trail by policy.