# MCP server

> The address, how clients connect, what they can discover, and every tool your agent can call, generated from the server itself.

Page: https://revisemy.com/docs/mcp

ReviseMy is a remote MCP server over streamable HTTP. One address serves every client:

```text
https://revisemy.com/mcp/revisemy
```

POST JSON-RPC to it. A `GET` answers a JSON `405`, which is expected. Authenticate with a [try token](/docs/authentication#try-tokens) as a Bearer header, or let the client [connect with OAuth](/docs/authentication#connect-oauth).

## Adding it

Most assistants have a one-step setup on [Connectors](/connectors). For anything else, the config is the same shape:

```json
{
  "mcpServers": {
    "revisemy": {
      "url": "https://revisemy.com/mcp/revisemy",
      "headers": { "Authorization": "Bearer YOUR_TRY_TOKEN" }
    }
  }
}
```

Claude Code also has a plugin that adds the server and a `design-checkup` skill:

```text
/plugin marketplace add heyderekj/revisemy
/plugin install revisemy@revisemy
```

## Discovery

| Document | What it's for |
|---|---|
| [`/.well-known/mcp/server-card.json`](/.well-known/mcp/server-card.json) | Name, version, endpoint, tools and prompts, read from the server |
| `/.well-known/oauth-protected-resource/mcp/revisemy` | OAuth resource metadata for clients that connect by signing in |
| [`/llms.txt`](/llms.txt) | A short index of the site and the tools, for agents |
| `server.json` in the repo | The entry in the MCP registry, `io.github.heyderekj/revisemy` |

## The checkup prompt

The server offers one prompt, `design_checkup_loop`. It walks an agent through the whole loop: capture, `create_review`, share the link, poll `get_review`, follow `next_action`. Hosts that show prompts list it as a starting point.

## Reviews inside the chat

In hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview), such as Claude and VS Code, `create_review` and `get_review` also render the review inline. The person marks and decides without leaving the conversation. Everywhere else your agent pastes `review_url`. The loop is the same either way, and your agent should always paste the link.

Three tools exist only for that inline view: `add_mark`, `decide_review` and `verify_mark`. They're hidden from the model, and an agent must never call them, because approving and verifying stay with the person.

## Tool reference

These are the tools your agent sees, with the descriptions it reads. Each one's REST twin is on [REST API](/docs/rest-api).

### `create_review`

Use when the person wants something visual (a page, screen, email or deck) checked, proofed, marked up or signed off before it ships, or after you change UI. Not for code or PR review. Start or continue a design checkup loop: provide exactly one source — capture_url+page_url (public website), html (email), pdf (slides), or images (local UI as data URLs) — and get a review URL for the human. Pass parent_id after changes_requested to open the next pass with a fresh source. Call add_findings before sharing if you want a subagent critique. In MCP Apps hosts the review renders inline so the human can start marking right away. A website capture takes 20 to 60 seconds: tell the human you are capturing the page before you call this.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `title` | string | Yes | Short title for this checkup pass |
| `context` | string | No | What should the human look at on this pass? Set a new focus for each pass — do not reuse the previous pass’s notes blindly. |
| `type` | "ui" \| "website" \| "presentation" \| "email" | No | What kind of content this is — ui (default), website, slide (`presentation`), or email. Drives the second-opinion lens: emails get CTA/dark-mode/client checks, slides get slide-density checks, websites get above-the-fold/responsive checks. Follow-up passes inherit the parent type. |
| `page_url` | string | No | Live page URL. Required with capture_url:true for server-side website capture (desktop + mobile) — on a follow-up pass it defaults to the parent review page_url. Metadata only when using images/html/pdf — does not trigger capture on its own. |
| `webhook_url` | string | No | Optional https URL POSTed when the human decides (event review.decided, HMAC-signed with the review token) — lets pipelines gate on approval instead of polling. Follow-up passes inherit it. |
| `parent_id` | string | No | Previous review id when opening the next pass after changes_requested |
| `images` | array of string | No | Local or app UI: 1–5 screenshots as data URLs or base64 (costs 1 credit). Prefer this for localhost — do not send http://localhost to remote capture. For public websites use capture_url. Provide exactly one source: images, capture_url, pdf, or html. |
| `capture_url` | boolean | No | Capture page_url server-side (desktop + mobile; costs 5 credits). Public URLs only — for localhost use images data URLs. Requires REVISEMY_CAPTURE_DRIVER=hosted\|browsershot. On [capture_not_configured] or [capture_provider_failed], immediately retry once with images. On [insufficient_credits], call get_billing (monthly refill); create_checkout only if pricing is enabled. |
| `pdf` | string | No | A PDF as https URL or base64 — rendered one screenshot per page, max 5 (type defaults to slide / `presentation`). |
| `html` | string | No | Raw HTML of an email — rendered at ~600px like a mail client (type defaults to email). Requires REVISEMY_CAPTURE_DRIVER. On [capture_not_configured] or [capture_provider_failed], fall back to images with data URLs. |

### `get_review`

Poll the design checkup: status, next_action, human marks in work_packets.pins (authoritative), second_opinion hints. Follow next_action — wait, apply marks + create next pass, or stop when approved. In MCP Apps hosts this renders the review inline so the human can mark and decide there.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `id` | string | Yes | The review public id returned by create_review |

### `list_reviews`

List recent design reviews for this try token only. Returns pass #, status, next_action, and outstanding / awaiting-verification counts — not full work packets. Call get_review for pins.

No parameters.

### `add_screenshot`

Append another screenshot to an open design review that is still waiting on feedback.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `id` | string | Yes | The review public id |
| `image` | string | Yes | Screenshot as https URL, data URL, or base64 |

### `add_findings`

Act as a design-reviewer subagent: push suggestion/a11y/polish findings into an open review for the human to see alongside their marks. Never use must-fix — human marks stay authoritative.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `id` | string | Yes | The review public id |
| `findings` | array of object | Yes | List of {severity?, body, area?, screenshot_index?, related_pin?} — severity must be suggestion\|a11y\|polish |

### `resolve_marks`

Report progress on human marks while fixing them: set each mark to in_progress or resolved (with a short note on what you changed). When resolving, optionally attach after_image — a screenshot of the fixed area — so the human sees a before/after. Verifying stays the human's job — never claim a mark is done for them.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `id` | string | Yes | The review public id |
| `marks` | array of object | Yes | List of {id, status?, note?, after_image?}. id is the mark id from work_packets.pins[].id. status is "in_progress" or "resolved" (default resolved). note describes what you changed. after_image is an optional screenshot of the fixed area (https URL, data URL, or base64) shown to the human as a before/after. |

### `request_second_opinion`

Re-queue the Cloud second-opinion job (free checklist + optional OpenAI vision) for a review. Findings are suggestions only and never change review status.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `id` | string | Yes | The review public id |
| `screenshot_index` | integer | No | Optional screenshot index; omit to refresh all shots |

### `get_billing`

Show this workspace plan, credits remaining, and the burn table (images/pdf=1, html=3, capture_url=5). Try is 20 credits that renew monthly (no rollover); purchased pack credits never expire and are spent last. When credits run out and checkout is available, offer Plus or a credit pack via create_checkout; otherwise wait for the monthly refill.

No parameters.

### `create_checkout`

Start a checkout link for the human: product "plus" (default — Plus subscription, monthly credits) or "credits_50" (one-time 50-credit pack that never expires; works on Try or Plus). If the workspace is already on Plus, use credits_50. Immediately paste share_markdown / checkout_url into chat (never only say “finish payment in the browser”).

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `product` | "plus" \| "credits_50" | No | plus (default): monthly subscription. credits_50: one-time 50-credit pack, never expires. |

### `create_portal`

Open the billing manage page so the human can view receipts, update their payment method, buy a credit pack, or cancel Plus (billing runs through Polar). Returns portal_url — immediately paste it into chat as the markdown share block (never only say “open the billing page”).

No parameters.

### `cancel_subscription`

Cancel Plus for this workspace (stops renewal; keeps Plus until the current period ends, then Try with leftover credits only — no new grant). Requires confirm:true after the human asks to cancel. Purchased pack credits are kept. For payment-method or receipt changes, use create_portal instead.

| Parameter | Type | Required | What it is |
|---|---|---|---|
| `confirm` | boolean | No | Must be true. Only set after the human explicitly asks to cancel Plus. |

## Errors

A tool that can't do what was asked answers with an MCP error whose message starts with a bracketed code your agent can branch on:

| Code | What to do |
|---|---|
| `[capture_not_configured]` | This server can't render `html`. Retry once with `images` as data URLs. |
| `[capture_provider_failed]` | Rendering failed. Retry once with `images`. |
| `[insufficient_credits]` | Out of credits. Call `get_billing` for when they refill. |

A failed `capture_url` doesn't error. The review still opens, so there's always a link, but its shot is a blank placeholder (`meta.origin` is `capture_failed`) and the reply names the failure. Your agent should add the page with `add_screenshot`, desktop and mobile, before it shares the link.

Anything else is a plain sentence meant for your agent to read and act on.