# Add Reviewable to your agent

Install Reviewable with no credential or review link. If an agent was given only the Reviewable URL, start with the canonical [agent onboarding guide](agent-onboarding.md). For the native Codex/Claude bundle and portable make-it-reviewable skill, use [Connect your agent](/agents). When your agent needs access, it starts a browser authorization for you.

## 1. Install it

### Codex

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

### Claude Code

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

### Another stdio MCP host

Add a local stdio server named `reviewable` that runs:

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

## Publish a generated artifact

`make-it-reviewable` is an explicit action. Give it one self-contained `.html` or `.htm` artifact; it asks when the candidate is missing or ambiguous and never substitutes a handoff. It rejects Office/PDF/image/URL inputs and returns only the private owner URL. Share from Reviewable after opening it.

## 2. Authorize when access is needed

Ask your agent to connect Reviewable. It calls `start_web_authorization` and prints an approval URL and a short verification code.

Open the URL. If this browser has no workspace key, create one there and save the one-time recovery copy before continuing. Type the code your agent printed into the page, choose the scope, and approve:

- **Read one review** — read-only access to that review.
- **Read the workspace** — read-only access to reviews in the workspace.
- **Read and create private reviews** — workspace read access plus private-review creation.

The page never shows the verification code. Typing the code from the agent proves that you are approving the MCP process that requested the connection. The MCP receives a scoped, revocable grant, never your workspace key.

A collaborator with only a reviewer link can approve the read-one-review scope for that shared review. Rotating that reviewer link revokes grants created from it.

After approval, ask the agent to call `check_authorization`. It exchanges the approval once. The review tools are already listed; until the check succeeds, calling one returns a not-connected error. A host that caches its tool list and ignores the tools-changed notification can call them without re-listing or restarting. You do not need to approve again. A host that already cached the older four-tool list must load the tool list again; restarting that host does not refresh the cache.

## Managing and recovering access

- Revoke a connection in Reviewable workspace settings. The next MCP request reports that access was revoked and asks for a new browser authorization.
- Replacing a workspace key is a security reset: it revokes every grant issued by that key. Create a new connection afterward.
- Changing browsers or clearing browser storage does not disconnect an already paired MCP. A different MCP installation or profile needs its own approval.
- If the service or network is temporarily unreachable, the MCP reports `temporarily_unavailable` and keeps its stored grant. Try again shortly; do not reauthorize unless it reports revoked access.

The MCP stores its own grant in the OS credential store when available. Otherwise it uses a permission-protected local file and tells the agent which backend is in use. That fallback file is **not encrypted**.

## Advanced configuration and corporate networks

`REVIEWABLE_MCP_WORKSPACE_KEY` and `REVIEWABLE_MCP_REVIEWS` remain supported advanced routes and take precedence over a stored browser grant. Keep either value in local MCP configuration, never in chat. Workspace-key access can create private HTML reviews; reviewer-link access remains read-only.

Some corporate networks block `https://bereviewable.com` outright. It looks like the approval page will not load and the agent cannot connect; the service may never receive the request. Ask IT to allowlist `bereviewable.com`. Until then, set `REVIEWABLE_MCP_BASE_URL` to a reachable self-hosted, staging, or approved service origin as the interim route. This override is an advanced local configuration, not a public documentation route.

For detailed tool, access, and security semantics, read [MCP tools](mcp-tools.md).