# Reviewable agent onboarding

This is the canonical public route for an agent that receives only a Reviewable URL. Follow the steps in order. Do not ask a person for a workspace key, reviewer URL, or a copy of these instructions.

## 1. Discover the installation

Reviewable is available as a public stdio MCP package:

- npm package: [`reviewable-artifacts-mcp`](https://www.npmjs.com/package/reviewable-artifacts-mcp)
- MCP Registry name: `com.bereviewable/reviewable-artifacts`
- native Codex and Claude Code bundle: [`bereviewable/reviewable-agents`](https://github.com/bereviewable/reviewable-agents)

Prefer the native bundle when the host supports it because it installs both the MCP and the explicit `make-it-reviewable` skill. Otherwise install the MCP directly. The installed package version and its `tools/list` response are the runtime authority; do not infer a capability from an unreleased source tree or from an old conversation.

## 2. Install without credentials

Use the host's existing MCP configuration. Do not replace unrelated MCP entries, and do not add credentials or environment variables just to install Reviewable.

### Codex

```sh
codex plugin marketplace add bereviewable/reviewable-agents
codex plugin add reviewable-agent-plugin@reviewable
```

Reload plugins after installation. For MCP-only use:

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

### Claude Code

```sh
claude plugin marketplace add bereviewable/reviewable-agents
claude plugin install reviewable-agent-plugin@reviewable
```

Run `/reload-plugins` after installation. For MCP-only use:

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

### Any stdio MCP host

Register a local server called `reviewable` with this command:

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

If the host supports Agent Skills, install the `skills/make-it-reviewable/` folder from the public bundle for the named publishing action. The MCP works without that skill.

## 3. Verify the unconfigured installation

Reload or reconnect the MCP server, then list its tools. An installation with no credentials must expose these connection tools:

| Tool | Use |
| --- | --- |
| `get_connection_state` | Read the non-secret state and the next action. |
| `start_web_authorization` | Begin a scoped browser approval. |
| `check_authorization` | Exchange an approved attempt once. |
| `disconnect` | Remove this local MCP profile's grant. |

Call `get_connection_state` first. A normal new installation reports that it is not connected. It must not reveal reviews or require a workspace key. If the server does not start, inspect the host's local MCP logs, confirm that Node meets the package's declared engine, and retry the same installation command. Do not work around a startup error by asking for credentials.

## 4. Request access only when the task needs it

Read-only discovery and publishing are different scopes. Choose the smallest scope that serves the explicit task. For example, publishing a selected HTML file requires `workspace_create`; reading a shared review requires review access.

When access is needed:

1. Call `start_web_authorization` with the least scope.
2. Give the person the returned approval URL and verification code.
3. Wait for that person to complete approval in their browser. The person types the code into the page; never paste a workspace key into chat or configuration.
4. Call `check_authorization` once approval is complete.
5. Re-list tools or reconnect if the host does not refresh after the server's tools-changed notification.

The resulting grant is scoped and revocable. If the state is `temporarily_unavailable`, retry later without reauthorizing. If it is revoked or expired, begin a new browser authorization. Never claim a connection or authorization succeeded unless the MCP reports that state.

## 5. Use the granted tools

After authorization, re-list tools and follow each tool's description and schema. For a publishing request, the `make-it-reviewable` skill requires one explicitly selected, self-contained `.html` or `.htm` file and must not publish automatically after generating an artifact. Return the private owner URL after a successful create; the owner chooses any sharing in Reviewable.

Read [MCP quickstart](mcp-quickstart.md) for host commands and [MCP tools](mcp-tools.md) for scope, recovery, and tool semantics.

## Network and self-hosted use

`https://bereviewable.com` is the hosted origin. If it is unavailable from the local network, ask the network owner to allowlist it. `REVIEWABLE_MCP_BASE_URL` is an advanced local override for a reachable self-hosted, staging, loopback, or approved interim origin. Do not change it without a supplied reachable origin, and never place credentials in that setting.