# MCP tools

`reviewable-artifacts-mcp` is an upcoming read-only stdio MCP package. Its five tools are snake_case and advertise `readOnlyHint: true`.

## Tool contract

| Tool | Semantics |
| --- | --- |
| `list_reviews` | Lists only reviews represented by configured share URLs. It never enumerates reviews on the service. |
| `get_review` | Composes the session GET with the consolidations list. Returns the authorized role, decision and undecided counts, and the latest snapshot id plus creation time for inexpensive freshness polling. |
| `get_threads` | Returns review threads; accepts a disposition filter. |
| `get_handoff` | Fetches the latest snapshot or a requested snapshot id in JSON or Markdown. The export payload is passed through byte-identical. |
| `get_artifact` | Returns current artifact HTML, echoes its current version id, and flags whether it differs from a requested snapshot's `version_ref.id`. `include_targets` optionally includes projection targets for anchor resolution. |

`get_artifact` mismatch means post-snapshot drift; resolve anchors as described in [Stable anchors](stable-anchors.md).

**Consumer note:** handoffs are immutable, additive-only within v1, and describe external regeneration. `feedback_type` and `severity` are reserved/non-normative; do not branch on them.

## Configuration

Set `REVIEWABLE_MCP_REVIEWS` to one or more reviewer share URLs. The package reads their session ids and fragment capabilities locally, then sends each capability as `x-review-capability` to its matching service.

```sh
REVIEWABLE_MCP_REVIEWS='https://review.example/?session=review-id#cap=reviewer-capability' \
  npx -y reviewable-artifacts-mcp
```

Claude Code configuration:

```sh
claude mcp add --transport stdio reviewable-artifacts \
  --env REVIEWABLE_MCP_REVIEWS='https://review.example/?session=review-id#cap=reviewer-capability' \
  -- npx -y reviewable-artifacts-mcp
```

For multiple reviews, supply multiple share URLs in `REVIEWABLE_MCP_REVIEWS` using the package's documented separator.

## Security

- Use reviewer links as the MCP credential, never owner links.
- Never paste capability URLs into committed files, issue trackers, or logs.
- Tools never echo capabilities in results or errors; stdout remains protocol-clean and diagnostics stay on stderr.
- Treat a share URL like a password. Rotate or revoke it when it is exposed.