MCP server

Harvv runs a hosted Model Context Protocol server so AI coding agents (GitHub Copilot, Cursor, Claude, Windsurf, Zed, Lovable) can read your behavioral findings and install the pixel without leaving the editor. One endpoint, one bearer token, scoped to your account.

Just want it connected? The one-click quick start for VS Code, Copilot, Cursor, Claude Desktop, Windsurf and Zed lives at harvv.com/install/copilot. On Lovable, use harvv.com/install/lovable. This page is the full reference: transport, tools, parameters, and troubleshooting.

Endpoint

https://harvv.com/mcp

The aliases /mcp/lovable and /mcp/harvv resolve to the same server. Point any MCP client at the base /mcp URL.

Connect your client

Every client uses the same standard MCP config: an HTTP server URL plus an Authorization: Bearer header. Only the file or UI you paste it into changes.

Authentication

Transport (custom clients)

The server speaks JSON-RPC 2.0 over Streamable HTTP (MCP spec 2025-03-26 and later). For a hand-rolled client:

curl -X POST https://harvv.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"list_my_sites","arguments":{}}}'

Tools

36 tools, listed from the same registry tools/list serves, so this page cannot drift from the server. Every tool is read-only and scoped to the account behind your token. Tools that act on a site take site_id; on an account with more than one site it is required, and list_my_sites is how you get it. The setup tools and get_help are free; data tools count against the monthly credit allowance only when they answer (a timeout or a bad argument is not charged).

Setup and help

Free. Onboarding, verification, navigation, the product guide, and a self-check for a draft conclusion.

check_install

Check whether the Harvv pixel is firing on a public URL.

check_slack_integration (no arguments)

Check whether this account's Slack integration is actually wired up correctly, and say what to fix if not.

get_dashboard_url

Get a deep link to the Harvv dashboard for a site on your account.

get_help

How to USE Harvv: product documentation and best practice, not site data.

install_pixel

Get the Harvv pixel install snippet for a site on this account, with framework-specific guidance for where to place it.

list_my_sites (no arguments)

List every site belonging to the Harvv account this MCP token is scoped to.

red_team

Red Team an analysis you are about to present: attack your own conclusion before the user sees it.

Data tools

Metered. Behavioral findings, page-level friction and behavior, traffic, conversion, speed, SEO and AI visibility for your sites. Every numeric response carries window, counted and sample blocks that say what was measured.

annotate_change

Record a change the team made to the site (a deploy, a theme edit, a campaign launch, a price change) on a date, so every later comparison can show it beside a rise or drop.

dismiss_issue

Dismiss a finding on this account's site with a reason, exactly as the dashboard's Dismiss button does.

get_ad_spend

What this site's ads COST and what the ad platform says they returned: spend, impressions, clicks, conversions and conversion value per campaign, a daily series, and (Google Ads) the change history: who changed a budget, bid strategy, status, landing page, ad

get_ad_traffic_quality

How the traffic from each AD CAMPAIGN behaves after it lands, compared against this site's own non-paid traffic: bounce, rage clicks, dead clicks, how far people scroll, whether they touch a form.

get_ai_bot_activity

AI crawler activity on a site, including robots.txt VIOLATIONS (bots requesting paths your robots.txt disallows).

get_ai_recommendations

Which pages AI assistants (ChatGPT, Perplexity, Gemini, Claude, Copilot) actually sent visitors to, and whether those pages emit structured data a model can quote.

get_audience_state

Who the visitors are, as categories: signed-in vs anonymous vs unknown, whether logged-in CMS staff are in the numbers, whether they arrived with a cart, and first-time vs returning.

get_commerce_funnel

Get the site's commerce funnel (browsed collection → viewed product → added to cart → viewed cart → began checkout → purchased) plus form starts/submits, with session counts, event counts, and total cart value where the site tags values.

get_conversion_path

Find the interaction that gates conversion on a page, and how many visitors never reach it.

get_conversions

REVENUE AND CONVERSIONS, from two independent sources.

get_dismissed_findings

What this account has already dismissed on a site: findings marked dismissed with the reason given (false positive, noise, intentional, duplicate, fixed already, not useful) or auto-expired by housekeeping.

get_element_clicks

Which ELEMENTS get clicked most, ranked by click volume, optionally narrowed to a page path or an element-name filter (e.g.

get_fleet_benchmark

Compare this site with the whole Harvv fleet on five behaviour rates over the last 30 days: share of sessions on phones, sessions with a dead click, sessions with a rage click, sessions that never scroll past a quarter of the page, and dead clicks per 1,000 se

get_friction_findings

ALIAS of get_issues (kept for older clients; prefer get_issues, which returns the same findings with fix text and a status filter).

get_issue_sessions

The individual visitor sessions affected by ONE specific issue, by issue_id (get it from get_issues or get_friction_findings).

get_issues

The UX issues Harvv has detected on a site, with a plain-English fix for each: what is broken, how many sessions it affects, its status, and the recommended fix.

get_js_errors

JavaScript exceptions and failed network requests on the site, grouped so you can name WHICH page and WHICH file or URL is breaking.

get_layout_changes

When did this site's layout or theme last change, and which findings the change may have invalidated.

get_page_behavior

How visitors BEHAVE on a page (or the whole site) beyond clicks: what share left mid-visit to check something elsewhere (tab-away), stopped and hesitated (with the median pause), copied text like a price or SKU (comparison shopping), held the site open in mult

get_page_friction

Per-page friction breakdown for a site on your account: dead clicks, rage clicks, and affected sessions per page, plus the top stuck elements.

get_performance

Core Web Vitals for a site on your account, from real visitor sessions: LCP / INP / CLS / TTFB p50+p75, plus the slowest pages by LCP, over the last N days (default 7, max 30).

get_search_console

Google Search Console data Harvv has synced for a site (needs the Search Console connection in the dashboard): totals, the top queries by clicks, CTR leaks (queries ranking well that under-click their expected rate) and almost-ranking queries (positions 8 to 2

get_seo_insights

Per-page SEO + GEO (AI-search) insights for a site, built from what the pixel already captured on the REAL rendered page of each URL your visitors loaded — no codebase needed.

get_site_stack

The site's technology stack as Harvv last observed it: platform, theme, and the ACTIVE plugin list with an honest role for each.

get_traffic_sources

Where a site's traffic actually comes from, classified into channels: Organic search, Paid search, Paid social, Social, Email, Referral, Direct — with sessions + share for each over the last N days (default 7, max 30).

get_traffic_summary

Traffic overview for a site on your account: sessions, unique visitors, top pages, the DEVICE split (mobile / desktop / tablet, as `devices`) and the BROWSER split (safari / chrome / edge / firefox / other, as `browsers`), referrer/source split, and bounce-equ

mark_issue_fixed

Record that a finding has been fixed, exactly as the dashboard's Mark fixed action does: it moves to verification, and Harvv measures the before/after on the next detection pass (call verify_finding after 14 days for the numbers).

set_conversion_goal

Tell Harvv what counts as a conversion on a site: 'form' (a form submit, call or booking), 'add_to_cart' (a store: cart and checkout), or 'cv' (the site sends its own conversion event).

verify_finding

Re-check ONE finding against RECENT data to answer 'is this still happening right now?'.

Example: get_friction_findings

Request:

{"jsonrpc":"2.0","id":4,"method":"tools/call",
 "params":{"name":"get_friction_findings","arguments":{"days":7}}}

The result is a content block whose text is JSON:

{
  "ok": true,
  "site": { "id": "c8d5fc24-...", "name": "Acme", "domain": "acme.com" },
  "window": { "days": 7, "requested_days": 7, "clamped": false,
              "min_days": 1, "max_days": 30 },
  "headline": { "sessions": 1840, "events": 41230,
                "dead_clicks": 212, "rage_clicks": 64,
                "unit": "count", "window_days": 7 },
  "findings": [
    { "id": "8231", "type": "dead_click",
      "title": "Dead clicks on pricing CTA",
      "element": "button.upgrade-cta", "priority": "high",
      "summary": "212 clicks on a button with no handler ...",
      "dashboard_url": "https://harvv.com/app/site/c8d5fc24-.../issue/8231" }
  ]
}

All headline counts are totals over the whole window, not per-day averages. Findings come sorted high priority first.

Troubleshooting

Every tool returns 401. The transport is fine (the auth check was reached); your token was rejected. The 401 body carries a reason code so you can tell which:
  • token_expired: the token reached the lifetime it was created with. An OAuth connector refreshes on its own; a pasted token is regenerated at harvv.com/app.
  • token_revoked: regenerate at harvv.com/app and reconnect.
  • token_not_found: mistyped, or from another account. Regenerate and reconnect.
  • wrong_scope: not a customer MCP token. Generate one from your dashboard.
The reason is in error.data.reason (JSON-RPC) and the WWW-Authenticate response header.
Tools show empty input schemas. If your client lists the tools but every inputSchema looks like {"properties":{}}, it cached an older catalog from before the site_id / url / days parameters shipped. Remove and re-add the Harvv connector (or refresh the connection) to re-fetch tools/list and pick up the current schemas. list_my_sites genuinely takes no arguments, so an empty schema there is correct.

check_install reports not-installed on a Lovable preview. Use the published URL, not the id-preview--*.lovable.app wrapper (see check_install above).