MCP quickstart

What MetricSpot’s MCP server does

MetricSpot’s MCP server is a hosted Model Context Protocol endpoint that lets AI agents run SEO and AI-readability audits without leaving the chat. It wraps the same audit pipeline that powers metricspot.com, exposes six tools, and ships scores plus rule-level findings as JSON.

Capabilities:

• Run a one-shot anonymous audit on any public URL (no auth, 1/IP/24h).
• Queue full audits with Core Web Vitals against your plan allowance.
• Fetch a prior audit by id, with all findings and recommendations.
• List recent audits, deduplicated by URL.
• Get a signed PDF download URL for the branded report.
• Pull a 28-day organic traffic snapshot (GA4 + GSC) when Google is linked.

Transports:

• Streamable HTTP at https://mcp.metricspot.com/mcp (hosted).
• stdio via the @metricspot/mcp-server npm package (npx -y @metricspot/mcp-server) for self-hosted, air-gapped, or local-only setups.

Why it matters

Agents that can audit a page in-line stop hallucinating SEO advice. Once the MCP server is wired in, Claude Code can answer “is this PR going to tank our title tags?” with real findings instead of guesses, and Cursor can refuse to ship a deploy until the structured-data findings come back green.

Concrete workflows:

• An audit-on-PR bot calls run_audit when a preview deploy ships, then polls get_audit and posts a comment with the delta versus the last audit on the same URL.
• A content reviewer agent grabs get_audit findings for a new blog URL and rewrites the title, meta description, and intro until the on-page and AI modules pass.

How to use it

The hosted server speaks the MCP Streamable HTTP transport defined in the official spec. Five of the six tools require an API key as a Bearer token; run_audit_anonymous does not.

Auth header for the five authenticated tools:

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Mint a key from your MetricSpot account at app.metricspot.com/settings/api-keys. Sign up free, verify your email, then create a key in Settings → API keys. You can have up to 10 active keys per account.

Rate limits and quotas:

Tool	Auth	Limit
run_audit_anonymous	none	1 audit per IP per 24 hours
run_audit	required	Free 10/mo, Starter 50/mo, Pro unlimited
get_audit, list_audits, get_audit_pdf, get_organic_traffic	required	no per-tool limit beyond plan

Add to Claude Code

claude mcp add --transport http metricspot https://mcp.metricspot.com/mcp \
  --header "Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Then prompt:

Run a MetricSpot audit on https://example.com and summarize the top three critical findings.

Add to Cursor

In ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "metricspot": {
      "url": "https://mcp.metricspot.com/mcp",
      "headers": {
        "Authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Then prompt:

Using the metricspot MCP server, audit https://example.com and tell me which on-page rules failed.

Add to Zed

In ~/.config/zed/settings.json:

{
  "context_servers": {
    "metricspot": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.metricspot.com/mcp", "--header", "Authorization:Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"]
      }
    }
  }
}

Local stdio transport

Run the published npm package as a stdio subprocess. Most MCP clients accept this shape:

{
  "mcpServers": {
    "metricspot": {
      "command": "npx",
      "args": ["-y", "@metricspot/mcp-server"],
      "env": {
        "MCP_API_KEY": "ms_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

The stdio entry reads Authorization from the MCP_API_KEY env var (alias: METRICSPOT_API_KEY). Omit it to only use run_audit_anonymous.

Raw HTTP call (Node)

const res = await fetch("https://mcp.metricspot.com/mcp", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    accept: "application/json, text/event-stream",
    authorization: "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: { name: "run_audit_anonymous", arguments: { url: "https://example.com" } },
  }),
});
const json = await res.json();
console.log(json.result.content[0].text);

Raw HTTP call (Python)

import httpx

r = httpx.post(
    "https://mcp.metricspot.com/mcp",
    headers={
        "content-type": "application/json",
        "accept": "application/json, text/event-stream",
        "authorization": "Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {"name": "list_audits", "arguments": {"limit": 10}},
    },
    timeout=60.0,
)
print(r.json())

Common errors

Code	When	Action
UNAUTHORIZED (401)	Missing or invalid Bearer token	Mint a key at app.metricspot.com/settings/api-keys
RATE_LIMITED (429)	Anonymous IP cap or plan throttle	Wait, or upgrade and call run_audit
QUOTA_EXCEEDED (402)	Monthly audit allowance used up	Upgrade at https://app.metricspot.com/billing
INVALID_URL (400)	URL not parseable or non-public	Pass an absolute https:// URL
AUDIT_NOT_FOUND (404)	audit_id doesn’t belong to your account	Call list_audits to find a valid id
UPSTREAM_FAILED (5xx)	App backend hiccup	Retry with backoff; retryable: true is set

Frequently asked questions

Is the MCP server free to use?

The run_audit_anonymous tool is free but capped at 1 audit per IP per 24 hours, with no Core Web Vitals. The five authenticated tools count against your MetricSpot plan: Free includes 10 audits per month, Starter 50, Pro unlimited. List, get, PDF, and organic-traffic tools have no per-call cost beyond the audit they reference.

Do I have to use Streamable HTTP, or can I run it locally?

Both work. The hosted endpoint at https://mcp.metricspot.com/mcp is the easiest path and is what claude mcp add --transport http expects. For air-gapped, self-hosted, or local-only setups, install the @metricspot/mcp-server npm package and point your client at npx -y @metricspot/mcp-server.

Where do the docs links inside findings point?

Every finding includes a docs_url pointing to https://metricspot.com/docs/<rule-slug>/, the same rule reference pages the dashboard links to. Agents can fetch them to read the canonical explanation and fix steps for any failing check.