— Sviluppatori · MCP

Server MCP.

Dai a Claude, a Cursor o a un agente n8n undici strumenti SeoPrimo: leggono i tuoi siti, avviano audit e analisi e ti dicono il prezzo prima di spendere i crediti.

tool pronti

HTTP

Streamable, senza sessioni

Bearer

la stessa chiave dell'API

— Connessione

Un indirizzo, una chiave.

Indirizzo: https://seoprimo.it/mcp
Trasporto: Streamable HTTP, senza stato. Ogni richiesta è un POST JSON-RPC con risposta application/json; non ci sono sessioni e il canale dal server al client (GET) risponde 405.
Autenticazione: Authorization: Bearer sp_live_… su ogni richiesta, con la stessa chiave dell'API REST. Crea la chiave in Integrazioni, Chiavi API.
Versioni del protocollo: 2025-06-18 e 2025-03-26.
Limite: 60 richieste al minuto per chiave, lo stesso conteggio dell'API REST.
Scope: ogni tool controlla lo scope della chiave per l'azione richiesta (read per leggere, write per avviare). Una chiave solo read può usare soltanto le azioni di lettura.

— Configurazione

Collega il tuo client.

Sostituisci sp_live_... con la tua chiave. Se il client lo permette, tienila in una variabile d'ambiente e non nel file.

Claude Desktop

Claude Desktop apre i server remoti tramite mcp-remote. Aggiungi questo a claude_desktop_config.json e riavvia l'app. L'intestazione passa da una variabile d'ambiente perché gli spazi negli argomenti danno problemi su Windows.

JSON

{
  "mcpServers": {
    "seoprimo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://seoprimo.it/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${SEOPRIMO_AUTH}"
      ],
      "env": {
        "SEOPRIMO_AUTH": "Bearer sp_live_..."
      }
    }
  }
}

Claude Code

shell

claude mcp add --transport http seoprimo https://seoprimo.it/mcp --header "Authorization: Bearer sp_live_..."

Poi, dentro Claude Code, /mcp mostra i tool di SeoPrimo.

Cursor

In ~/.cursor/mcp.json (o nel file del progetto, .cursor/mcp.json):

JSON

{
  "mcpServers": {
    "seoprimo": {
      "url": "https://seoprimo.it/mcp",
      "headers": {
        "Authorization": "Bearer sp_live_..."
      }
    }
  }
}

n8n

Nel nodo MCP Client Tool di un AI Agent: Endpoint = https://seoprimo.it/mcp, trasporto HTTP Streamable, autenticazione Header Auth con la credenziale «SeoPrimo API». I passaggi completi sono nella guida a n8n.

— Strumenti

Gli undici tool.

Ogni tool ha un'azione scelta con un parametro, così gli strumenti restano pochi e l'agente non si perde. Tutti gli strumenti a pagamento accettano dry_run: true.

Gli undici tool del server MCP
Tool	Cosa fa	Parametri chiave	Scope	Crediti
`seoprimo_sites`	Elenca i siti dell'attività o ne aggiunge uno. Ogni altro tool parte da un site_id di qui.	`action: list \| add`	`read` per list, `write` per add	Gratis
`seoprimo_audit`	Audit rapido (Score, cinque pilastri, sintesi) o completo (scansione con il motore dati). L'audit completo è un lavoro lungo: segui l'esito con action=status e il run_id ricevuto.	`mode: quick \| full · action: start \| status`	`write` per start, `read` per status	Rapido: 10 crediti (restituiti se fallisce). Completo: scansione da 2 crediti (1 ogni 100 pagine), Lighthouse a parte
`seoprimo_keywords`	Idee di parole chiave dai seed, oppure volume, difficoltà, CPC e intento di un elenco.	`action: research \| metrics`	`write`	A crediti
`seoprimo_rankings`	Monitoraggio delle posizioni su Google: elenca, crea, controlla ora (lavoro lungo) e leggi l'esito.	`action: list \| create \| run \| status`	`read` per list e status, `write` per create e run	Creare è gratis, ogni controllo è a crediti
`seoprimo_backlinks`	Backlink del sito o di un altro dominio: panoramica o profilo paginato.	`action: overview \| profile`	`write`	A crediti
`seoprimo_competitors`	I domini che competono con il sito sulle parole chiave indicate.	-	`write`	A crediti
`seoprimo_ai_visibility`	Se ChatGPT e Google AI Overview citano il marchio. Una run per piattaforma.	-	`write`	A crediti, per piattaforma
`seoprimo_agent`	Avvia un agente AI sul sito (analisi_completa o report_mensile) e leggine il diario e il report. L'agente lavora qualche minuto: segui l'esito con action=status e il run_id ricevuto.	`action: start \| status · agent · budget_credits`	`write` per start, `read` per status	Fino a budget_credits (300 l'analisi completa, 150 il report mensile)
`seoprimo_score`	L'ultimo SeoPrimo Score completo (pilastri, controlli) e le ultime 12 misure.	-	`read`	Gratis
`seoprimo_report`	I report HTML del sito: elenco o lettura di uno.	`action: list \| get`	`read`	Gratis
`seoprimo_credits`	Il saldo dei crediti e i secchi da cui si consumano.	-	`read`	Gratis

— Crediti e sicurezza

Un agente che non sorprende.

Il prezzo prima. Con dry_run: true un tool a pagamento risponde con la stima e non spende niente. Nelle istruzioni dell'agente scrivi di chiamare sempre prima dry_run e di chiederti conferma sopra una soglia.
Nessun tool cancella. Non esiste un tool per eliminare siti o chiavi: l'agente può aggiungere siti e spendere crediti, non distruggere dati.
Errori leggibili. Crediti finiti, sito inesistente o scope mancante tornano come risultato del tool con isError: true: l'agente li legge e si regola. Gli errori di protocollo (chiave non valida, limite superato) hanno lo stato HTTP e il codice error dell'API.
Una chiave per agente. Dai a ogni agente la sua chiave, con il solo scope che gli serve: la revochi senza toccare gli altri.
Se lo chiami da un browser, l'intestazione Origin deve essere https://seoprimo.it: altre origini ricevono 403. I client da riga di comando, da editor o da server non mandano Origin e non sono toccati.

— Prova

Dalla riga di comando.

Per verificare chiave e indirizzo senza un client MCP puoi parlare JSON-RPC con curl: initialize, poi tools/list, poi la chiamata di un tool.

curl

export SEOPRIMO_KEY="sp_live_..."

# 1. initialize
curl -sS https://seoprimo.it/mcp \
  -H "Authorization: Bearer $SEOPRIMO_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize",
       "params": {"protocolVersion": "2025-06-18", "capabilities": {},
                  "clientInfo": {"name": "curl", "version": "1.0"}}}'

# 2. list the tools
curl -sS https://seoprimo.it/mcp \
  -H "Authorization: Bearer $SEOPRIMO_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# 3. call a tool (your credit balance)
curl -sS https://seoprimo.it/mcp \
  -H "Authorization: Bearer $SEOPRIMO_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "tools/call",
       "params": {"name": "seoprimo_credits", "arguments": {}}}'

Agenti al lavoro

Dieci tool,
il tuo agente.

Crea una chiave, incollala nella configurazione del tuo client e chiedi: «fai un audit rapido del mio sito».

Crea una chiave API Usa n8n

Cosa trovi nella guida

Chiave dal pannello

scope read e write

Configurazione del client

Claude, Cursor, n8n

Tool disponibili

dry_run sui tool a crediti