Guida rapida MCP

Cosa fa il server MCP di MetricSpot

Il server MCP di MetricSpot è un endpoint Model Context Protocol ospitato che permette agli agenti AI di eseguire audit SEO e di leggibilità AI senza uscire dalla chat. Incapsula la stessa pipeline di audit che alimenta metricspot.com, espone sei strumenti e restituisce punteggi e finding a livello di regola in formato JSON.

Funzionalità:

• Esegui un audit anonimo one-shot su qualsiasi URL pubblico (senza auth, 1/IP/24h).
• Metti in coda audit completi con Core Web Vitals secondo la disponibilità del tuo piano.
• Recupera un audit precedente tramite id, con tutti i finding e le raccomandazioni.
• Elenca gli audit recenti, deduplicati per URL.
• Ottieni un URL firmato di download per il report PDF brandizzato.
• Estrai uno snapshot di traffico organico a 28 giorni (GA4 + GSC) quando Google è collegato.

Trasporti:

• Streamable HTTP su https://mcp.metricspot.com/mcp (ospitato).
• stdio tramite il pacchetto npm @metricspot/mcp-server (npx -y @metricspot/mcp-server) per setup self-hosted, air-gapped o solo locali.

Perché è importante

Gli agenti che possono auditare una pagina in linea smettono di allucinare consigli SEO. Una volta collegato il server MCP, Claude Code può rispondere a “questa PR rovinerà i nostri title tag?” con finding reali invece di ipotesi, e Cursor può rifiutarsi di rilasciare un deploy finché i finding dei dati strutturati non tornano verdi.

Workflow concreti:

• Un bot di audit-su-PR chiama run_audit quando viene rilasciato un preview deploy, poi fa polling su get_audit e pubblica un commento con il delta rispetto all’ultimo audit dello stesso URL.
• Un agente revisore di contenuti recupera i finding di get_audit per l’URL di un nuovo blog post e riscrive title, meta description e introduzione finché i moduli on-page e AI passano.

Come usarlo

Il server ospitato parla il trasporto MCP Streamable HTTP definito nella specifica ufficiale. Cinque dei sei strumenti richiedono una API key come Bearer token; run_audit_anonymous no.

Header di autenticazione per i cinque strumenti autenticati:

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Genera le chiavi su https://app.metricspot.com/settings/api-keys.

Limiti di chiamata e quote:

Strumento	Auth	Limite
run_audit_anonymous	nessuna	1 audit per IP ogni 24 ore
run_audit	richiesta	Free 10/mese, Starter 50/mese, Pro illimitato
get_audit, list_audits, get_audit_pdf, get_organic_traffic	richiesta	nessun limite per-tool oltre al piano

Aggiungere a Claude Code

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

Poi chiedi:

Esegui un audit MetricSpot su https://example.com e riassumi i tre finding critici principali.

Aggiungere a Cursor

In ~/.cursor/mcp.json (globale) o .cursor/mcp.json (per progetto):

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

Poi chiedi:

Usando il server MCP metricspot, esegui l’audit di https://example.com e dimmi quali regole on-page sono fallite.

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

Trasporto stdio locale

Esegui il pacchetto npm pubblicato come sottoprocesso stdio. La maggior parte dei client MCP accetta questa forma:

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

L’entry stdio legge Authorization dalla variabile d’ambiente MCP_API_KEY (alias: METRICSPOT_API_KEY). Omettila per usare solo run_audit_anonymous.

Chiamata HTTP grezza (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);

Chiamata HTTP grezza (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())

Errori comuni

Codice	Quando	Azione
UNAUTHORIZED (401)	Bearer token mancante o non valido	Genera una chiave su https://app.metricspot.com/settings/api-keys
RATE_LIMITED (429)	Cap IP anonimo o throttle del piano	Attendi, o aggiorna e chiama run_audit
QUOTA_EXCEEDED (402)	Disponibilità mensile di audit esaurita	Aggiorna su https://app.metricspot.com/billing
INVALID_URL (400)	URL non parsabile o non pubblico	Passa un URL assoluto https://
AUDIT_NOT_FOUND (404)	audit_id non appartiene al tuo account	Chiama list_audits per trovare un id valido
UPSTREAM_FAILED (5xx)	Singhiozzo del backend dell’app	Riprova con backoff; retryable: true è impostato

Domande frequenti

Il server MCP è gratuito?

Lo strumento run_audit_anonymous è gratuito ma limitato a 1 audit per IP ogni 24 ore, senza Core Web Vitals. I cinque strumenti autenticati contano sul tuo piano MetricSpot: Free include 10 audit al mese, Starter 50, Pro illimitato. Gli strumenti list, get, PDF e organic-traffic non hanno costo per-chiamata oltre l’audit a cui si riferiscono.

Devo usare Streamable HTTP o posso eseguirlo in locale?

Funzionano entrambi. L’endpoint ospitato su https://mcp.metricspot.com/mcp è il percorso più semplice ed è quello che claude mcp add --transport http si aspetta. Per setup self-hosted, air-gapped o solo locali, installa il pacchetto npm @metricspot/mcp-server e punta il tuo client a npx -y @metricspot/mcp-server.

A cosa puntano i link docs all’interno dei finding?

Ogni finding include un docs_url che punta a https://metricspot.com/docs/<rule-slug>/, le stesse pagine di riferimento delle regole linkate dalla dashboard. Gli agenti possono recuperarle per leggere la spiegazione canonica e i passi di fix per qualsiasi check fallito.