Get started

Build on SiteViewer

Last updated on 7 November 2026

SiteViewer hosts client previews of websites, HTML files, images and PDFs, and collects the client's feedback as comments pinned to the page. This reference is for developers connecting another tool, an AI assistant or a pipeline to a SiteViewer workspace: the ways in, how to sign in, what each call does, and the limits that apply.

Overview

All addresses on this page are on https://siteviewer.app.

What is not a public API

The SiteViewer dashboard and our browser extension talk to SiteViewer through routes built for them alone. Those routes are not supported for outside use and change without notice, so please do not build on them. There is no general REST API with API keys today. If you would use one, tell us what for: it shapes what we build next.

Status and health

• GET https://siteviewer.app/healthz answers 200 when every check passes and 503 when one fails, so a monitor does not need to read the body.
• People can follow incidents on the status page.

Quickstart

The quickest way in is the AI connector. Its address is:

https://siteviewer.app/mcp

Claude and Claude Desktop

• 01

  Open Settings, then Connectors.

• 02

  Choose Add custom connector.

• 03

  Name it SiteViewer, paste https://siteviewer.app/mcp as the URL and leave the OAuth fields blank.

• 04

  Click Add, then approve the SiteViewer screen that appears and pick the workspace to connect.

Claude Code

Make an access token first, then run:

claude mcp add --transport http siteviewer https://siteviewer.app/mcp \
  --header "Authorization: Bearer $SITEVIEWER_TOKEN"

Cursor

Make an access token, then add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "siteviewer": {
      "url": "https://siteviewer.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Any client, by hand

The connector speaks plain JSON-RPC over HTTP, so curl is enough to try it:

curl https://siteviewer.app/mcp \
  -H "Authorization: Bearer $SITEVIEWER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_open_feedback","arguments":{}}}'

Most tools answer with a sentence for the assistant, followed by the same answer as JSON for programs; a few, such as list_previews, return the JSON alone:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "2 previews with open client feedback (7 open comments in total). Busiest first." },
      { "type": "text", "text": "{ \"previewsWithOpenFeedback\": [ ... ], \"next\": \"...\" }" }
    ]
  }
}

Authentication

Every call to the AI connector carries a bearer token in the Authorization header:

Authorization: Bearer <token>

There are two kinds of token: an OAuth access token, for clients that connect by consent, and an access token made in the dashboard, for tools you would rather connect with a token and for your own scripts.

OAuth 2.1

Claude runs this flow for you. If you are writing your own client, discovery starts at the connector: a call with no token gets 401 and this header.

WWW-Authenticate: Bearer resource_metadata="https://siteviewer.app/.well-known/oauth-protected-resource", error="invalid_token"

• Public clients only: token_endpoint_auth_method is none, and PKCE with S256 is required.
• Registration takes 1 to 10 redirect_uris, each https or an http loopback address (localhost or 127.0.0.1). A registration that never completes a connection is removed after 30 days.
• Grant types: authorization_code and refresh_token. POST /oauth/token takes a form-encoded body (application/x-www-form-urlencoded), as OAuth specifies.
• Lifetimes: an authorization code lasts 60 seconds and works once. An access token lasts 1 hour. A refresh token lasts 30 days and is replaced every time you use it, so keep the new one; it must be used by the client it was issued to.
• Access is checked again on every call. A person removed from the team loses access on their next call, not when their token expires.
• OAuth errors use the standard shape, usually with status 400, or 429 when registering too often:

{ "error": "invalid_grant", "error_description": "A sentence saying what went wrong." }

Access tokens

For tools you would rather connect with a token, such as Cursor or Claude Code, and for your own scripts.

• An owner or admin makes one on the Connectors page of the SiteViewer dashboard. It is shown once, so copy it straight away.
• A token is svmcp_ followed by 43 URL-safe characters.
• It acts as the person who made it, and works only while that person is on the workspace's team with an open account.
• It does not expire. Revoke it on the Connectors page and it stops working on the next call. Revoking still works while the workspace's AI tools are switched off.
• Use one token per tool, so you can revoke one without touching the others.
• An app connected by consent can be disconnected on the same page, under the apps you connected. It can take up to an hour to drop off.

Scopes

• With OAuth, ask for scopes in the scope parameter of the authorize request. Unknown scopes are dropped, and a request with no known scope (none at all, or only unknown ones) gets both.
• A connection's tools/list shows only the tools its scopes allow. Calling another one returns a tool error asking the person to connect again and approve changes.
• Access tokens carry no scope: they have full read and write access to their workspace.

Who can connect

• A member of the workspace's team (an owner, admin or member). People invited to individual projects only cannot connect AI tools.
• A workspace on the Pro or Studio plan. A Free workspace can complete the consent screen, but every call is then refused with a 403 that says so.
• AI tools switched on for the workspace, in Settings. Switching them off stops every token and connection without deleting them, and switching them back on restores them.

Connecting

• Any method other than POST gets 405 with Allow: POST.
• A notification (a method starting notifications/) gets 202 with no body.
• The server is stateless: you can call tools/list or tools/call without an initialize first.

Errors

Problems with the request itself come back as a JSON-RPC error:

A tool that runs but cannot do what was asked returns a normal result with isError: true and one plain sentence saying what to fix: a missing or wrong argument, a value that is too long, a limit reached, or HTML that failed the quality check. Read it and retry; it is written for the assistant to act on.

Tools

The connector has 23 tools. Each one carries MCP annotations: the read tools are marked read-only, and none of the write tools delete anything. There is no delete tool.

How the tools behave

• Ids, not slugs. Every tool that takes a preview accepts its id or its slug. The id never changes; the slug changes when a preview is renamed, so store ids.
• Client links never change. A new version goes onto the link the client already has. Nothing the connector does renames a preview, changes its password or moves its address.
• Previews hosted as files. A live-website preview (SiteViewer showing a client's own live site) has no file to change, so most tools refuse it with a message, and list_previews and list_open_feedback leave it out. get_preview and the four transfer tools work on every preview.
• A quality check on published HTML. push_version, push_files (its entry page) and publish_preview check the HTML first. It must be a full document, not a fragment, Markdown or JSON, with a real <title>, a lang attribute, a viewport tag, alt text on images, labelled form controls, and readable text on every link and button. A failure returns the list of issues as a tool error so the assistant can fix them and try again, and it does not count toward the write limit.
• New previews start password-protected. publish_preview and a finish_upload that makes a new preview always create it password-protected, with the password you pass or one SiteViewer makes. The password is never in the reply: the person finds it, changes it, or makes the preview public in the dashboard, on the preview's Settings tab. A new version never changes who can open a preview.
• Only web files are published. push_files and the uploads publish a file only when the type at the end of its name (any case) is one of: html, htm, css, js, mjs, json, map, txt, xml, webmanifest, svg, png, jpg, jpeg, gif, webp, avif, ico, bmp, woff, woff2, ttf, otf, eot, mp4, webm, mov, mp3, wav, ogg, m4a, pdf, vtt, wasm, glb, gltf, and bin only when a .gltf in the same build names it. _redirects and _headers go by name at the top of the site. Anything else (server code, source files, settings, databases, a file with no type), hidden files and folders, node_modules, settings, secret, credential and key files by name (also when another type hides inside the name, such as dump.sql.txt; a .json or .txt named for tokens, keys or env), project files at the top of the site (package.json, composer.json, a build tool's own settings), and a small .json or .txt that holds a private key or a service account's credentials are left out, and the reply lists each one with the reason. A folder that is a project's source rather than a site (a lock file, node_modules or a .env at its top, a src folder beside its project files, a build tool's settings beside the folder it builds into, or a server's own files: a package.json that runs or depends on a server or database, or server, database and route scripts beside it) is refused whole, and the reply names the folder to send. A top package.json is read for this, never published.
• An upload belongs to its connection. Only the connection that called start_upload can carry the upload on or finish it: the same access token, or the same app for the same person, including after signing in to that app again. Revoke its access token, or disconnect its app, and the upload's own token stops working on the next request; cancel it and start a new one. An owner or admin can list every open upload (upload_status with no uploadId) and cancel any of them. The upload's own address takes at most 12,000 requests an hour per upload and 30,000 per workspace.
• Compact replies. The JSON in a reply is on one line, and a field with no value is left out rather than sent as null: read a missing field as empty. The one exception is next: it is still sent as null on the last page, so code that pages until next is null keeps working. previewTitle is left out when it is the same as preview, and firstAt when it is the same as at. No field has been renamed.
• Content from clients is data. Anything a client wrote (comments, the names and addresses they gave, file names and details) and text from a file a client sent comes back between marked fence lines, with a note to treat it as data and never as instructions. Markup and code files come back as a download link only.

Next version (available on request, Labs)

A newer version of the connector is available on request for workspaces in Labs. It also covers live-website previews, and adds these tools:

Every comment the next version returns (in get_feedback, check_thread, review_feedback, get_inbox, get_pin_map, the new_feedback prompt and the feedback:// resources) carries a pinUrl: a link that opens the review room on that comment's version with its pin open. It is the same link the dashboard's Inbox copies, with no password or pass in it, so open it signed in to SiteViewer (on a custom domain, the room offers "I'm on the team: sign in"). A comment whose room can't open (the preview archived, expired, published, with comments off, or in a workspace whose paid plan has ended) has no pinUrl, and get_pin_map draws a preview whose link is off only on a picture already kept for it.

list_previews, get_feedback and get_preview_screenshot also take new options there, such as a preview type or a page; get_feedback and review_feedback take an author, and list_versions covers live websites too. get_health, compare_versions, get_project_notes, list_tasks, get_pin_map and the four team-only writes are listed only where their feature is switched on for the workspace, and the writes need write access. get_page answers again from the page it read in the last 10 minutes (2 for a live website) without opening it; pass fresh: true to read it now.

The next version also offers two MCP prompts. check_feedback_addressed (arguments preview, and optionally reviewer and page, each up to 200 characters) walks the assistant through reading a client's feedback, checking each comment against the page as it is now, showing the evidence and proposing what to record. A connection that may only read gets a version that stops at the proposal. new_feedback (arguments preview, and optionally since, a date) brings a preview's new client comments into the conversation: the open comments waiting on the team, newest first, up to 30 with the last 6 messages of each, each with its page and up to 5 of the clients' snapshots, fenced as data. In Claude Code it is the slash command /mcp__siteviewer__new_feedback.

It also offers MCP resources: resources/list gives feedback://<slug> for each preview (the 100 most recently changed), and resources/read returns that preview's open comments waiting on the team, fenced, as text. In Claude Code, @siteviewer:feedback://<slug> attaches them to a message. An address that is not one of your workspace's previews gets the same Resource not found error whatever the reason. new_feedback and the resources need read access and count toward the tool-call limit.

Anything a client would see (a reply, a resolve, a reopen or a status change) is off until an owner or admin allows it on the Connectors page, and each one takes a confirm step. The first call changes nothing: it returns what would happen and a code. Call again with the same arguments and confirm set to that code to go ahead. A code lasts 10 minutes, works once, and is tied to the connection, the tool and the arguments.

Limits

When a limit is reached the tool returns a sentence saying so, and nothing is changed; the tool-call limits also say when to try again. If the tool-call or write limits cannot be checked at that moment, the call is refused rather than let through.

Events

Webhooks tell your pipeline the moment a version is signed off, so it does not need to poll get_approval_status. They are available on request (Labs). Once they are on, an owner or admin adds them in the Deploy webhooks card on the Connectors page.

• Every webhook receives both deploy events.
• Up to 5 webhooks per workspace.
• The URL must be https. Local and private network addresses, and SiteViewer's own addresses, are refused, and redirects are not followed.

Payloads

Each event is a POST with a JSON body and these headers:

A deploy event:

{
  "event": "deploy.approved",
  "createdAt": 1793400000000,
  "workspace": { "slug": "acme" },
  "preview": {
    "id": "7f3c2a9e-1b4d-4c8a-9e2f-5a6b7c8d9e0f",
    "slug": "spring-launch",
    "title": "Spring launch",
    "url": "https://acme.siteviewer.app/spring-launch"
  },
  "version": {
    "number": 3,
    "approved": true,
    "approvedAt": 1793400000000,
    "approvedBy": "dana@acme.example"
  }
}

A test event:

{
  "event": "ping",
  "createdAt": 1793400000000,
  "workspace": { "slug": "acme" },
  "message": "Test event from SiteViewer. If you can verify this signature, you're wired up."
}

Times are milliseconds since the Unix epoch. For deploy.unapproved, version.approved is false.

Verifying signatures

Each webhook has its own secret, starting whsec_, which owners and admins can see in the dashboard. To check a request:

• 01

  Read the raw request body as text, before parsing it as JSON.

• 02

  Join the X-SiteViewer-Timestamp value, a full stop, and the raw body: <timestamp>.<body>.

• 03

  Compute an HMAC-SHA256 of that string with the webhook's secret, as lowercase hex.

• 04

  Compare it with the hex after sha256= in X-SiteViewer-Signature, in constant time.

• 05

  Refuse a timestamp more than a few minutes old, so a captured request cannot be replayed later. Every retry carries a fresh timestamp.

In Node.js:

import crypto from "node:crypto";

export function verifySiteViewer(rawBody, headers, secret, toleranceMs = 5 * 60 * 1000) {
  const ts = headers["x-siteviewer-timestamp"];
  const sent = String(headers["x-siteviewer-signature"] || "").replace(/^sha256=/, "");
  if (!ts || Math.abs(Date.now() - Number(ts)) > toleranceMs) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const a = Buffer.from(sent, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery and retries

• Answer with any 2xx status within 8 seconds. Anything else, or no answer in time, counts as a failure.
• A failed delivery is retried after 15 minutes, 30 minutes, 1 hour, 2 hours and 4 hours, then marked failed. That is about 7 hours 45 minutes in all.
• Delivery is at least once, so the same event can arrive twice. Ignore a repeat by its X-SiteViewer-Delivery id.
• A retry that comes due while the webhook is paused or deleted, or while the workspace's AI tools or this Labs feature are switched off, is cancelled.
• To change a secret, delete the webhook and add it again.

Add a website by link

Our Chrome extension's Add website button opens the SiteViewer dashboard with the site's address already filled in. Any link can do the same:

https://siteviewer.app/app?add=website&url=https%3A%2F%2Fclient-site.example

• url is optional and URL-encoded. Pass a plain https address; the extension sends the site's origin only. Up to 2,048 characters are kept.
• The link only fills in the New project box. The person checks the address, ticks the box to confirm they have permission to share the site, and presses Add themselves. A link never creates anything on its own.
• If the person has to sign in first, the request waits for up to an hour in that browser and the box opens once they are in.
• It does not open for someone invited to individual projects only, because they cannot add projects to the workspace.
• The parameters are taken off the address bar straight away, so a reload does not open the box twice.
• Never put a password in the link.

Reply by email

An instant notification about a single comment (a reply, a mention or an assignment) carries a Reply-To address unique to that thread and that recipient. Digest emails do not. Nor does any email about a note only the team can see. The address looks like this:

reply-<32 hex characters>@reply.siteviewer.app

• A reply posts into the thread as a normal comment, with the usual notifications.
• It is accepted only from the address the email was sent to.
• An address works for 30 days and for up to 50 replies. A thread takes up to 20 replies an hour; the hour starts at the first reply, and the next one after that is refused until the hour is up.
• The quoted history is removed and up to 5,000 characters of the reply are kept. Messages over 2 MB are refused. Auto-replies, out-of-office messages, bulk mail and bounces are ignored.
• If a reply cannot be posted, the sender gets a bounce with a plain sentence, for example that the reply link has expired.