MCP-Schnellstart

Was der MCP-Server von MetricSpot tut

Der MCP-Server von MetricSpot ist ein gehosteter Model-Context-Protocol-Endpunkt, mit dem KI-Agenten SEO- und KI-Lesbarkeits-Audits direkt im Chat ausführen können. Er kapselt dieselbe Audit-Pipeline, die metricspot.com antreibt, stellt sechs Tools bereit und liefert Scores und Befunde auf Regelebene als JSON.

Funktionen:

• Führe ein einmaliges anonymes Audit auf jeder öffentlichen URL aus (keine Auth, 1/IP/24h).
• Stelle vollständige Audits mit Core Web Vitals gegen dein Plan-Kontingent in die Warteschlange.
• Rufe ein früheres Audit per id ab, mit allen Befunden und Empfehlungen.
• Liste die letzten Audits auf, dedupliziert nach URL.
• Hole eine signierte PDF-Download-URL für den Markenreport.
• Ziehe eine 28-Tage-Momentaufnahme zum organischen Traffic (GA4 + GSC), wenn Google verknüpft ist.

Transporte:

• Streamable HTTP unter https://mcp.metricspot.com/mcp (gehostet).
• stdio über das npm-Paket @metricspot/mcp-server (npx -y @metricspot/mcp-server) für selbst gehostete, air-gapped oder lokale Setups.

Warum es wichtig ist

Agenten, die eine Seite inline auditieren können, hören auf, SEO-Ratschläge zu halluzinieren. Sobald der MCP-Server verdrahtet ist, kann Claude Code die Frage “wird dieser PR unsere Title-Tags zerstören?” mit echten Befunden statt mit Vermutungen beantworten, und Cursor kann sich weigern, ein Deploy auszuliefern, bis die Befunde zu strukturierten Daten grün zurückkommen.

Konkrete Workflows:

• Ein Audit-on-PR-Bot ruft run_audit auf, wenn ein Preview-Deploy ausgeliefert wird, pollt dann get_audit und postet einen Kommentar mit dem Delta zum letzten Audit auf derselben URL.
• Ein Content-Reviewer-Agent zieht die get_audit-Befunde für eine neue Blog-URL und schreibt Title, Meta-Description und Intro um, bis die On-Page- und AI-Module bestehen.

So nutzt du es

Der gehostete Server spricht den im offiziellen Spec definierten MCP-Streamable-HTTP-Transport. Fünf der sechs Tools benötigen einen API-Schlüssel als Bearer-Token; run_audit_anonymous nicht.

Auth-Header für die fünf authentifizierten Tools:

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Schlüssel erstellst du unter https://app.metricspot.com/settings/api-keys.

Rate-Limits und Kontingente:

Tool	Auth	Limit
run_audit_anonymous	keine	1 Audit pro IP pro 24 Stunden
run_audit	erforderlich	Free 10/Monat, Starter 50/Monat, Pro unbegrenzt
get_audit, list_audits, get_audit_pdf, get_organic_traffic	erforderlich	kein Per-Tool-Limit über den Plan hinaus

In Claude Code hinzufügen

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

Dann prompte:

Führe ein MetricSpot-Audit auf https://example.com aus und fasse die drei wichtigsten kritischen Befunde zusammen.

In Cursor hinzufügen

In ~/.cursor/mcp.json (global) oder .cursor/mcp.json (pro Projekt):

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

Dann prompte:

Auditiere mit dem metricspot-MCP-Server https://example.com und sag mir, welche On-Page-Regeln fehlgeschlagen sind.

In Zed hinzufügen

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"]
      }
    }
  }
}

Lokaler stdio-Transport

Starte das veröffentlichte npm-Paket als stdio-Subprozess. Die meisten MCP-Clients akzeptieren diese Form:

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

Der stdio-Einstiegspunkt liest Authorization aus der Umgebungsvariable MCP_API_KEY (Alias: METRICSPOT_API_KEY). Lass sie weg, um nur run_audit_anonymous zu nutzen.

Roher HTTP-Aufruf (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);

Roher HTTP-Aufruf (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())

Häufige Fehler

Code	Wann	Aktion
UNAUTHORIZED (401)	Fehlendes oder ungültiges Bearer-Token	Schlüssel ausstellen unter https://app.metricspot.com/settings/api-keys
RATE_LIMITED (429)	Anonymes IP-Cap oder Plan-Drossel	Warten oder upgraden und run_audit aufrufen
QUOTA_EXCEEDED (402)	Monatliches Audit-Kontingent aufgebraucht	Upgrade unter https://app.metricspot.com/billing
INVALID_URL (400)	URL nicht parsbar oder nicht öffentlich	Übergib eine absolute https://-URL
AUDIT_NOT_FOUND (404)	audit_id gehört nicht zu deinem Konto	Rufe list_audits auf, um eine gültige id zu finden
UPSTREAM_FAILED (5xx)	Backend-Aussetzer der App	Erneut mit Backoff versuchen; retryable: true ist gesetzt

Häufig gestellte Fragen

Ist die Nutzung des MCP-Servers kostenlos?

Das Tool run_audit_anonymous ist kostenlos, aber gedeckelt auf 1 Audit pro IP pro 24 Stunden, ohne Core Web Vitals. Die fünf authentifizierten Tools zählen auf dein MetricSpot-Plan-Kontingent: Free enthält 10 Audits pro Monat, Starter 50, Pro unbegrenzt. List-, Get-, PDF- und Organic-Traffic-Tools haben keine Per-Call-Kosten über das referenzierte Audit hinaus.

Muss ich Streamable HTTP nutzen, oder kann ich es lokal betreiben?

Beides funktioniert. Der gehostete Endpunkt unter https://mcp.metricspot.com/mcp ist der einfachste Weg und das, was claude mcp add --transport http erwartet. Für air-gapped, selbst gehostete oder rein lokale Setups installiere das npm-Paket @metricspot/mcp-server und richte deinen Client auf npx -y @metricspot/mcp-server.

Wohin verweisen die Docs-Links innerhalb der Befunde?

Jeder Befund enthält eine docs_url, die auf https://metricspot.com/docs/<rule-slug>/ zeigt, dieselben Regel-Referenzseiten, auf die auch das Dashboard verlinkt. Agenten können sie abrufen, um die kanonische Erklärung und die Fix-Schritte für jede fehlgeschlagene Prüfung zu lesen.