We built an MCP server!

By: Elliot Maguire

Building code with agents can feel a lot like playing Jenga. Somewhere in the loop of agent iterations and pasted review feedback, your agent tweaks something load-bearing to fix what was flagged a few rounds back. A short feature request turns into a tall, teetering tower of tiny bugs and file comments, with agents pulling at core building blocks from the bottom of the stack.

Instead of overengineering our prompts or rage-switching agent subscriptions, we built the Reviewable MCP server and CLI! It gives agents and scripts direct access to Reviewable's code review tools, providing the structure and revision history needed to maintain a solid codebase through large changes.

MCP at your service 🫡

If you haven't run into MCP yet, it's the emerging standard that lets coding agents talk to outside tools. We've built ours to help you and your agents work hand-in-hand on development revisions and code review.

With the MCP server in the agent's hands, you can use Reviewable's UI as a Mission Control while your agents pull instructions from your latest comments, or stay entirely in your agent thread while your agents maneuver the PR for you. We've already been using the MCP server in a variety of different workflows and could toot our own horn all day, but let's stop honking and start digging into the details:

Structured feedback

Using the MCP server, agents can take advantage of a core Reviewable feature, comment dispositions: satisfied, discussing, blocking, or working, so that you (or your agent) can take a stance on a discussion thread. Comments stay anchored to the revision they were made on, so a rebase or force-push doesn't wipe out the conversation, which matters a lot when your agent is working on a long-running PR.

Agent roles and identities

Each agent that you provision takes on one of three fixed roles. This affects its identity in Reviewable, the perspective from which it views pull requests, and whether its marks count toward review completion (customizable using completion conditions):

• Author — treats your PRs as its own, assuming the role of an author.
• Reviewer — treats the PR as somebody else's, even if it's your own.
• Replicant — no separate identity; acts entirely in your name.

You can also set a short tag (4 characters and a color) on the author and reviewer identities to help tell them apart in the UI:

Note that GitHub isn't aware of these agent identities; agent actions will show up as your own account name in GitHub.

Managing agent access

You can provision as many different agent identities as you want, and their access can be revoked or reissued at the click of a button. In case you need a little extra fencing around them, agents can be constrained to a subset of orgs and repos:

Built-in skills

We've built two skills into the MCP server and CLI: review-code and respond-to-review-feedback. Together, these two skills cover the full loop of code review and revisions based on review feedback, allowing agents to work through an entire PR on their own.

review-code

This skill provides the framework for performing a proper Reviewable PR review. It instructs your agent to look at files needing its attention, draft comments with dispositions, mark files as reviewed, and then publish the review.

You can see the exact commands the MCP server runs by typing reviewable skills review-code in your terminal.

respond-to-review-feedback

This skill instructs an agent how to respond to review feedback in Reviewable: inspect comments that need your attention, make requested code changes or push back on suggestions, and even publish on push so your review feedback and generated code are published simultaneously.

The MCP server instructs your agent not to guess which review tool to use on vague prompts like "respond to feedback on pr 8". If you've got more than one review tool available (say, Reviewable and gh) and haven't said which you prefer, it'll ask once and remember your answer.

Workflows

The MCP server and CLI are together quite flexible. One-off prompts are great for granular work, and the built-in skills fit nicely into larger workflows or agent skills.

Here are a couple of practical workflows we've been enjoying, as well as a few other pro-tips to help smooth out your daily reviewing:

Keep it in the threads

Since agents can use Reviewable on your behalf, you can perform an entire Reviewable code review, including comments and file marks, all from inside your agent thread. This one's for the headless power-users who don't own a computer mouse.

1. Draft a code review: Ask your agent to use the Reviewable MCP to review a PR, but to outline proposed review drafts here before publishing. If relevant, ask it to leave reproduction steps or tests open for you to verify yourself.
2. Polish and publish: Work with your agent to refine the review, asking questions, pushing back, adding your own findings, then publish once it feels right.
3. Incremental re-reviews: When new commits land, just redo steps 1 and 2. The review-code skill will compare against your agent's last review marks, so your agent won't waste time on anything it's already reviewed.

Steps 1 and 2 heavily rely on prompting, so we recommend making this into a custom agent skill that calls review-code under the hood. It can help to instruct your agent to use a specific response structure to make things easier on the eyes: always list draft comments and file marks at the end of each response, or weave them into the output for a more conversational approach. You might find your agent's "plan mode" to be of use here as well.

Cheapest reviewers first

Best to not lead with your queen: this three-round workflow uses the respond-to-review-feedback skill to have agents respond to your own feedback first, then the review bots, and then the humans. Iterating in a draft PR before the whole gang shows up saves you and your team both time and tokens.

0. Draft PR: Have your agent write some code, then open a draft PR.
1. Self-review: Review the PR in Reviewable, leaving comments and file marks as you go, then ask your agent to respond to review feedback. Repeat until you're satisfied, then mark the PR ready for review to summon the review bots.
2. Bot review: Review bots swarm in (we've been using Devin and Codex), scrutinizing your code as you guide them along, pushing back or @-mentioning your agent to redirect. Then ask your agent to respond. Repeat until the bots are satisfied.
3. Request human reviewers: Humans review, agent responds. Repeat and merge.

Silent self-review

We recently changed how author review marks are handled in Reviewable. By default, author review marks (including those made by agents with an author identity) no longer count towards completion and are shown differently in the UI. This means that you can use your PR as a workspace: marking files and leaving comments for your agents without any of it counting toward completion.

This is especially useful when using a draft PR, where you can review, iterate, and have agents respond to feedback before making the PR public (as seen in the cheapest reviewers first workflow above).

Review agent drafts in Reviewable

Using a replicant role, tell your agent to perform a code review or respond to a PR but to leave its comments as drafts in Reviewable. That way you can proofread your agent's drafted comments and review marks in Reviewable before publishing them. Note that this only works for replicants, as author and reviewer identities' drafts belong to that agent's own account and won't be visible in the Reviewable UI.

Split responsibilities across agents

Run two MCP servers, one author, one reviewer, and tell your agent which to use for which task: author for respond-to-review-feedback, and reviewer for review-code.

Run a third as a replicant to do things on your behalf: "provide summaries of all my open PRs" or "acknowledge any new comments". That way you won't introduce extra agent footprints to the participants panel across reviews your agent touches.

CLI

We've surfaced all of this as a plain CLI too. Things like reviewable review state, reviewable review discussions create, reviewable review files mark-reviewed, and more, are all callable directly from a script, CI job, or a git hook.

You can use it for more robust PR automations: like posting in Slack or filing a ticket when a blocking discussion shows up on an important PR, assigning it to or @-mentioning anyone with a working disposition, running a weekly job that roasts reviewers who are causing reviews to stall, or checking review state on every PR going into a release to create a readiness report.

Getting started

The reviewable package is available via npm. Check out our docs for the full setup, including how to provision agent tokens and identities.

This thing is still pretty new, so we'd love to hear how you're using it or if there's a workflow that isn't yet supported: open an issue or chat with us directly.

We hope your agents love using these new tools as much as our agents do!

🧑🏼‍💻🧙🏽🥷🧑🏻‍🚀🧑🏾‍⚕️🧌🤹🏻⛷️🪿🤖📎🕵️🐰🧑🏿‍⚖️🧑🏻‍🍳🧑🏽‍🚒🕵🏿‍♀️🦆🐢👻🦉🧑🏾‍🎨👽