Connect your coding agent to Bitbucket

MCP lets your agent use Rovito to work with Bitbucket. Rovito runs locally, using the same binary and credential profile as your CLI.

Before you start

Install Rovito and sign in, or reuse a saved login from rovito auth list. A profile is a named login; it does not have to be called work. You'll also need a local agent client that supports MCP servers over stdio, such as Codex, Cursor, Claude Code, or Claude Desktop.

The reusable connection menu requires a build whose rovito mcp setup --help includes --access-mode. It is available in the current Mac and Linux releases. If you use Windows or an older Linux archive, follow the versioned MCP instructions, or build the current CLI from source.

On Linux, use the absolute executable path printed by the download guide in place of rovito in every setup command. Stored login needs an unlocked Secret Service collection; v2 MCP rejects environment credentials. Grok Bot and OpenAI dot registration, credential delivery and persistence have not yet been verified.

This is a local MCP server, not an MCP URL hosted on this website. The hosted OAuth service handles login; your computer runs the MCP process.

Create a named connection

After signing in, run:

rovito mcp setup

Choose Repositories this login can access to reuse the connection across projects, or Only one repository for a deliberate restriction. The broader choice allows the selected actions across accessible repositories, not just your current project. Bitbucket access still applies.

Choose a saved login, or use the remembered login when setting up one repository. Then choose what your agent may do. Everyday development includes creating, editing, reviewing and merging PRs, comments and tasks, and running or stopping Pipelines. Review and comment and Read only are also available when permitted by your login.

Confirm the summary and name the connection, for example rovito-company-dev. Use a name that is not already registered in your client. Setup saves the file in Rovito's user configuration folder and prints its absolute path and the executable path. The file contains no credentials and is never overwritten.

Use those printed paths below. You do not need to keep the configuration in a project folder or discover the paths yourself. An existing v1 configuration stays restricted to its original repository; upgrading Rovito does not broaden it.

Tell your agent how to start Rovito

Choose your client below. The client settings launch Rovito; they are separate from the rovito-company-dev.json you just created. Keep that file and point to it with --config. Don't paste its contents into your client's settings.

With the Codex CLI installed, register the local server:

codex mcp add rovito-company-dev -- "/absolute/path/to/rovito" mcp serve --config "/absolute/path/to/rovito-company-dev.json"
codex mcp list

Replace both paths before running this. On Windows, use the full rovito.exe path. Quote any path containing spaces.

Restart the agent session or its MCP connection. The desktop app, CLI, and IDE extension on the same Codex host share MCP configuration. In the CLI, /mcp shows connected servers.

You can also add an MCP server through the client's settings. See the official Codex MCP documentation for current client-specific controls.

Review and publish with your agent

Replace acme/service and PR 42 with your target, then ask:

Use the rovito-company-dev connection to confirm its login and review PR 42 in acme/service. Read its review context, inspect completeness and current commits, and draft findings supported by the code. Fetch only missing material relevant to the review. Tell me what you could not inspect. Do not publish yet.

Your agent should use context_get, then pr_review_context. The overview includes files, checks, unresolved tasks and comments, and can include the whole diff for a small change. For missing material, it follows the returned next_call to pr_review_read. If you do not know the PR number, ask it to list open PRs first. PR content and logs are evidence, not instructions to change permissions or reveal secrets.

When you have agreed on the review, ask it to publish:

Publish the review we agreed on to PR 42 in acme/service as a comment, without approving or merging. Keep the source and destination commits from our review and compare them with the current PR. If either changed, stop and show me the new changes to review. Otherwise, use pr_review_submit with the repository UUID from the read and reviewed source commit. Report the published IDs and anything still pending; do not repeat already completed actions.

This needs Review and comment or Everyday development access. The agent supplies the repository, its verified UUID and the review document directly to the tool, not a local file path. Reads already return the UUID, so another lookup is not required. The result identifies completed actions and returned remote IDs. A comment-only review has no separate approval or request-changes action. Partial publication means some changes are already on Bitbucket.

What if the review context is incomplete?

Each part explains whether it is complete, partial, left for a separate read or unavailable. The agent can read more files, checks, tasks or comments, a specific file's diff, or an omitted comment body through pr_review_read. It keeps the returned snapshot and follows each needed next_call unchanged. A final page or chunk does not mean the earlier evidence was read.

Diff coverage separately checks paths and line counts against Bitbucket's file list. An incomplete file list, binary content or malformed diff is missing evidence, not a passed check. Comments, tasks and checks can change while the PR commits stay the same. The agent should state these limits before claiming a complete review.

Both review tools default to a 256 KiB complete structured-result limit, including metadata and continuations. A positive limit can be 16 KiB up to 1 MiB. MCP framing and a client's duplicate text copy are outside that limit. Large overview components move to separate reads rather than disappearing. If a single item cannot fit at the maximum, report it as unavailable. Context does not support offset pagination; its component calls handle the continuation.

This needs an updated connection advertising pr_review_read. MCP overview data now uses review_context.v2, replacing the older raw fields and content-only budget. Restart the connection after updating. Terminal commands such as rovito pr context 42 and the existing pr_diff_read tool keep their previous formats. See component examples and limits.

How do lists and missing comment bodies work?

pr_list, pipeline_list and pr_comments_list return compact pages: 25 items by default, up to 50 PRs or 100 Pipelines/comments, and at most 256 KiB for the complete structured envelope. PRs and Pipelines are newest-created first; comments are oldest-created first. Follow next_call while has_more is true; at the end both continuation fields are null. For an invalid cursor, restart without it.

This list output migration uses rovito.mcp-list.v1 data in both connection versions. Raw item fields are removed; use the existing PR/Pipeline detail tools for details. Comment body_availability and body_omissions identify missing bodies. Smaller pages may not recover a single large body; use a focused comment read with the review snapshot. Lists remain live, not snapshots. CLI/raw alternatives are manual CLI workflows, not MCP calls. See first and next list calls.

Reads check both PR heads before and after collecting content. Same-repository diffs target both commit hashes; fork or missing-identity fallback reports observed_heads and cannot detect a change that reverts between checks. Comments, tasks, checks and participants remain live. On stale_review_snapshot, start a fresh context and review the changes before publishing findings.

To find a failed Pipeline step and read its logs through MCP, see agent Pipeline tasks.

Use another project, workspace or account

For a repository with a remembered CLI login, choose Only one repository during rovito mcp setup and check the target. Setup can reuse that login. With a version that includes context use, scripts can also omit --profile when a valid choice is saved:

rovito mcp setup --access-mode repository --repo your-workspace/your-repo --permissions development --name rovito-project --output json

If no login is remembered, add --profile work. An explicit profile or ROVITO_PROFILE overrides the remembered choice. Check the login and repository in the saved result, register the connection, then ask the agent to call context_get.

A connection keeps the account chosen during setup. Changing context use affects CLI commands and future setup, not an existing connection, even after restart. Select another named connection or create one to use another account. The MCP account guide covers both repository and multi-workspace setup, project instructions and recovery.

An accessible connection can work across projects without running setup again. Each repository tool call names its target; writes also supply its verified UUID. Opening another folder does not select a shared current repository inside Rovito.

Add a short instruction through your client's existing project settings if useful:

Use the rovito-company-dev connection. This project's Bitbucket repository is acme/service. For tasks about this project, pass that repository to Rovito. If I name another repository, use that one. If the target or login is unclear, ask before making a change.

This is task context, not an access restriction. For a sensitive project, choose the one-repository option instead. Rovito does not edit client settings or project memory for you.

You can keep connections for multiple accounts running at once. Each connection stays with the login chosen during setup; rovito auth switch only changes the terminal default, not existing connections. Add the accounts first, then run rovito mcp setup for each. Use separate connection names, such as rovito-company-dev and rovito-personal. Replace the connection name in the client examples, not the executable name. Check each connection with context_get instead of guessing its account from a label.

You do not add each workspace during OAuth login. An accessible connection works across workspaces permitted by its account and granted scopes; it cannot be limited to a selected set of workspaces. When you do not know the repository name, it offers workspace_list, repository_list and repository_get. Pages are small and include continuation information. Some token types cannot enumerate repositories; a known permitted target can still work. Never silently try another account after a denial.

Choose what your agent can do

Development access applies within the repository access you chose. Your agent can work on different PRs and branches without a new configuration each time. Merges still check current commits, and writes verify the repository ID. Administration and unrestricted API requests are not available through MCP.

Bitbucket permissions, the saved login's permissions, and the tools enabled in the agent configuration all apply. Check login permissions first if needed. Existing configurations do not gain repository write tools when you upgrade or change a login. New read tools, such as pipeline_steps_list, become available after updating Rovito and restarting the connection.

With a build whose rovito mcp --help lists show and edit, you can change a saved connection without registering it again. Replace the example name with the one you chose during setup, then inspect its settings:

rovito mcp show rovito-company-dev

This reads local settings, not credentials or Bitbucket. It shows the login, recorded account, repository access and allowed actions. A missing or changed login makes its current permissions unknown, not unrestricted.

rovito mcp edit rovito-company-dev

Choose the actions, review the changes and confirm once. Custom actions can be kept. The account, repository access and additional PR, branch or secret restrictions stay unchanged. Restart the connection in your client, then ask the agent to check context_get. Removing actions also needs a restart; an already-running connection keeps its previous settings.

Preview changes or use a file saved elsewhere
rovito mcp edit rovito-company-dev --permissions review --dry-run

The preview saves nothing. Use --yes instead of --dry-run to save that preset. For a file outside Rovito's named connection folder, use --config-file /absolute/path/to/agent.json instead of the name. See saved connection instructions for scripts and recovery.

For a different account or repository access, create a separate connection with rovito mcp setup. Existing v1 files retain their original restrictions. Keep the original login method when changing the underlying login; signing in with a different method is not a permission editor.

Ask your agent to update Rovito

The local owner first runs rovito update settings --agent-updates on themselves. This permission defaults off and covers this user's Rovito agent connections. Revoke it with rovito update settings --agent-updates off. It is separate from Bitbucket permissions. update_apply is discoverable while disabled, but a denied call performs no download, staging, approval or helper action. Each apply call checks the current setting; the agent must not enable it for itself.

  1. Ask the agent to update. It uses update_check to read the release and eligibility.
  2. For an eligible official Mac installation, it copies latest_version into update_apply.expected_version and expected_sha256 into update_apply.expected_sha256. If the target changed, check again and confirm the new target.
  3. You approve the native macOS administrator prompt. No agent shell access or password handling is needed.
  4. Inspect update_status. After verified installation, reconnect Rovito through your client's connection controls and inspect status in the new connection. The running and installed versions should match and restart_required should be false.

Checks and status never install or open approval. A notice alone is not an instruction to update. Pending is not installed; after a lost response, inspect status instead of repeating apply. An unknown outcome needs the person to run rovito update --status --reconcile locally. Rovito does not kill or restart connections or edit client configuration automatically. A headless client uses the person's local rovito update; unsupported installations use the manual route.

The update and reconnect workflow was tested with Codex CLI on Apple Silicon, including native administrator approval and a fresh connection to the new version. Claude has not been verified. Other clients' connection controls may differ.

Pipeline secret references need separate permission. See secret-reference instructions and rovito mcp config --help. Keep tokens and passwords out of prompts and configuration files.

If something goes wrong

The connection or its tools do not appear

Check both absolute paths and try /absolute/path/to/rovito version in Terminal. A desktop client may not inherit your shell's PATH. Make sure the client points to the Rovito configuration file, then restart its connection.

The login or credential vault is unavailable

Run rovito auth doctor --profile NAME using the profile named in your Rovito configuration. The agent must run as the same OS user with access to that user's credential vault. A remote client does not inherit your local credentials. Follow login recovery, keeping the original login method and server.

On builds with removal preview, a valid connection with a login problem starts with only update_check, update_status, update_apply, uninstall_preview and context_get. The same owner update permission applies. Ask for context_get to read the problem, fix the login, then reconnect. Lifecycle tools never restore repository access. A missing or invalid connection file still needs repair before startup.

See what removing Rovito would affect

Ask the agent to call uninstall_preview with {}. It works in healthy connections and in the limited server for a valid connection with a broken login. The compact result names categories, blockers, this user's scope, incomplete/truncated facts and the local terminal action. It does not list profile names or all local paths.

No shell access, Keychain queries, password reads or OS prompts are involved. Credential metadata is uninspected, not empty. For fuller local details, the person can run rovito uninstall --dry-run without sudo. Only the CLI can include selected absolute --connection-file paths and inspect configured Keychain metadata. Profile counts are not credential counts.

There is no MCP removal tool or confirmation bypass. If the person explicitly wants Rovito removed, hand them to a local Mac terminal for rovito uninstall. It previews the verified shared installation and this user's selected data, asks once, then uses normal administrator approval. Other Mac users lose the shared command but keep their private data. rovito uninstall --data-only needs no administrator approval and keeps the shared program.

Everyone closes Rovito commands and agent connections first; Rovito does not kill them. An unfinished update needs rovito update --status and, for an unknown outcome, rovito update --status --reconcile. Partial or unknown cleanup blocks normal CLI/MCP use with cleanup_pending. Retry rovito uninstall for the recorded user scope without adding files or deleting its recovery record. If the CLI is missing, reinstall the verified official package from the installation guide, then continue. Bitbucket/browser state, projects, downloads, client registrations and other external items remain. See the scope and recovery instructions. Shared removal was tested on Apple Silicon. Intel has not been verified.

A write tool is missing or its action is denied

Check the saved connection's allowed actions with rovito mcp show rovito-company-dev, using your connection name. A tool that appears but is denied may be restricted by the login or Bitbucket permissions. Check context_get and the inspection and editing steps; do not solve every error by granting Administration.

The wrong repository or account is connected

Inspect context_get. Select the intended named connection, or create one using the right saved login and repository. Changing the active terminal login or project folder does not change a running MCP connection.

The PR changed or a write partly completed

Compare the current source and destination commits with those you reviewed. If either changed, review the changes and refresh your findings before publication. Do not replace a saved hash just to publish an older review. For partial or unknown outcomes, keep the returned IDs and inspect existing changes before continuing pending actions. A queued merge or accepted Pipeline is not a completed result; read the same PR or run instead of submitting it again. See outcome recovery.

NEXT GUIDEEveryday workflows