MCP Server

Install and configure @thewebratings/mcp so Claude Code, Cursor, and other MCP clients can onboard a website with 7 purpose-built tools

@thewebratings/mcp is the official TheWebRatings MCP (Model Context Protocol) server. It wraps the agent onboarding flow in 7 tools, so an MCP-capable coding agent can claim, verify, and instrument a website without hand-crafting HTTP requests.

Runs via npx — no global install required. Node.js 18+.

Prerequisites

A setup token (twr_agent_…) minted by the site owner in Dashboard → Settings at thewebratings.com. See token security below for scope and expiry.

Install: Claude Code

claude mcp add thewebratings -e TWR_SETUP_TOKEN=twr_agent_8fK2mQ9xL4vN7pR3sT6wY1zB5cD0eH8j -- npx -y @thewebratings/mcp

Verify with claude mcp list — thewebratings should be listed as connected.

Install: Cursor

Add to ~/.cursor/mcp.json (create the file if it does not exist):

{
  "mcpServers": {
    "thewebratings": {
      "command": "npx",
      "args": ["-y", "@thewebratings/mcp"],
      "env": {
        "TWR_SETUP_TOKEN": "twr_agent_8fK2mQ9xL4vN7pR3sT6wY1zB5cD0eH8j"
      }
    }
  }
}

Restart Cursor, then check Settings → MCP to confirm the server shows its 7 tools.

For a project-scoped setup, put the same JSON in .cursor/mcp.json at the project root instead — but do not commit a file containing a real token.

Tools

Tool	Description	Arguments
`get_setup_status`	Stateless source of truth: current claim/verification/widget state plus `next_steps`. Call first and whenever unsure.	`domain` (string, required)
`claim_website`	Create (or re-link) the website record for a domain.	`domain` (required); `name`, `app_url`, `website_url`, `category` (optional)
`get_verification_meta_tag`	Start HTML claim verification and return the `<meta name="twr-site-verification">` tag to place in the site's `<head>`.	`domain` (required)
`verify_website`	Check the deployed meta tag and mark the domain verified; auto-creates the default API key on success.	`domain` (required)
`get_widget_snippets`	Return the collection snippet (with real API key), display script tag, and badge/bar/carousel snippets, plus plan flags and URLs.	`domain` (required)
`validate_installation`	Fetch a live page URL and report which widgets and the meta tag were found on it.	`url` (string, required — public https URL on the claimed domain)
`get_public_profile`	Return the public profile info (slug, profile URL, rating summary) for the website.	`domain` (required)

Tool order for a full onboarding: get_setup_status → claim_website → get_verification_meta_tag → (edit the customer's codebase, deploy) → verify_website → get_widget_snippets → (install snippets per the placement rules) → validate_installation.

Tool errors surface the same error codes as the HTTP API — handle them per the error table.

Environment variables

Variable	Required	Description
`TWR_SETUP_TOKEN`	Yes	Setup token (`twr_agent_…`) minted by the site owner in Dashboard → Settings
`TWR_API_URL`	No	API base override. Default: `https://api.thewebratings.com/api/v1`. Only set for staging/self-hosted testing

Token security

Scope: a setup token can only call the setup endpoints listed above — it cannot read reviews, change billing, or manage the account. On first use it becomes bound to one domain; it will return TOKEN_SCOPE for any other domain.
Expiry: tokens expire 7 days after creation (TOKEN_EXPIRED afterwards).
Revocation: the owner can revoke a token at any time in Dashboard → Settings (TOKEN_REVOKED afterwards). Revoke tokens as soon as onboarding is complete.
Handling: pass the token only via the TWR_SETUP_TOKEN environment variable. Never commit it to the customer's repository, print it in logs or PR descriptions, or embed it in installed snippets (the widget uses the separate twr_live_… API key, not the setup token).