# Reviewable MCP

Reviewable turns team feedback into better AI-generated work. [`reviewable-artifacts-mcp`](https://www.npmjs.com/package/reviewable-artifacts-mcp) is a stdio MCP server with no required dependencies, also listed in the [MCP Registry](https://registry.modelcontextprotocol.io/). Its one optional dependency, `@napi-rs/keyring`, is used for OS keyring storage; the server falls back to a local file without it.

If an agent was given only a Reviewable URL, it should follow the [agent onboarding guide](https://bereviewable.com/docs/protocol/agent-onboarding.md). For host-specific commands, read the [MCP quickstart](https://bereviewable.com/docs/protocol/mcp-quickstart.md).

## Install without credentials

Register the server with no workspace key or reviewer link. This package runs on Node.js 20 or newer (`npx` on Node 20 does not need a Node 22 package). The Reviewable server itself still requires Node.js 22.13 or newer. When access is needed, your agent calls `start_web_authorization` and returns an approval URL and short verification code.

```sh
claude mcp add --transport stdio reviewable-artifacts \
  -- npx -y reviewable-artifacts-mcp
```

For Codex:

```sh
codex mcp add reviewable -- npx -y reviewable-artifacts-mcp
```

Open the URL, create a workspace key if this browser has none, save its one-time recovery copy, type the code printed by your agent, choose a scope, and approve. The page never displays the code. The MCP receives only a scoped, revocable grant — never the workspace key. The review tools are listed before authorization. Until `check_authorization` reports connected, calling one returns `Not connected. Call start_web_authorization.` A host that caches `tools/list` and ignores the tools-changed notification can call those tools after authorization without re-listing or restarting. A host that already cached the older four-tool list must load the tool list again; restarting that host does not refresh the cache, so remove the server and add it again. A call outside the granted scope returns a scope error.

Scopes are read one review, read the workspace, read plus create private reviews, manage artifact preparations, and explore one review. Preparation access accepts explicit local HTML/ZIP paths, exposes durable diagnostics and can supply missing resources; exploration accepts only bounded pointer/keyboard/scroll/resize operations in the isolated runtime. Neither can publish links or make human review decisions. A collaborator with a reviewer link can approve read or exploration access to that review only. Rotating that link revokes the grant derived from it; replacing a workspace key revokes every grant it issued.

## Storage and recovery

The MCP stores its own grant in the OS credential store when possible and reports the backend in use. If unavailable, it uses a permission-protected local file; that fallback is not encrypted. Changing browsers does not revoke an already paired MCP profile, but another profile requires separate approval. A network or service outage reports `temporarily_unavailable` and leaves the grant intact; a revoked connection requires fresh browser authorization.

## Advanced compatibility configuration

`REVIEWABLE_MCP_WORKSPACE_KEY` and `REVIEWABLE_MCP_REVIEWS` remain supported advanced routes. They take precedence over a stored browser grant and are useful for existing configurations, keyring-unavailable environments, or a network that blocks the hosted service. Keep them in local MCP configuration, out of chat, logs, and committed files. Never use an owner link as reviewer credentials.

`REVIEWABLE_MCP_BASE_URL` overrides the hosted origin for self-hosted, staging, loopback, or an approved interim origin. Some corporate networks block `https://bereviewable.com` before a request reaches the service: the approval page will not load and the agent cannot connect. Ask IT to allowlist `bereviewable.com`; use a reachable base URL until then.

See [the MCP tool contract](https://bereviewable.com/docs/protocol/mcp-tools.md) for tool semantics, connection states, `agent-context/v1`, `execution-package/v1`, and the reproducible `review-evidence/v1` sidecar.