MCPDati socialTutorial API

Guida a SocQ MCP: recuperare dati social in Cursor, Claude e Codex

Collega Codex, Claude, Cursor e VS Code a SocQ MCP, scegli l’ambito degli strumenti e raccogli dati social pubblici tramite attività asincrone.

SocQAggiornato il 10 settembre 202611 min di lettura

Un client AI può parlare di dati social senza sapere quale endpoint chiamare. È un problema di instradamento, non un secondo catalogo. SocQ MCP espone le stesse API di dati pubblici usate da REST: un unico indirizzo ospitato, tre ambiti di strumenti e lo stesso modello di attività asincrone.

Questa guida mostra come collegare Codex, Claude, Cursor e VS Code, scegliere un ambito, inviare una raccolta e continuare a interrogare la stessa attività. I dettagli di configurazione si trovano nella pagina MCP. Copia da lì la configurazione generata, invece di inventare campi.

SocQ MCP

Risposta rapida: collegati all’endpoint Streamable HTTP ospitato https://api.socq.ai/mcp. La scoperta funziona senza chiave. La raccolta richiede una chiave API di SocQ. La modalità compatta segue il percorso socq_search_endpoints → socq_describe_endpoint → socq_execute, poi prosegue con l’attività restituita. Non considerare quella chiamata execute come un dump sincrono di tutte le righe.

API ufficiali delle piattaforme o un MCP pubblico?

Le API ufficiali di Instagram, X, YouTube e prodotti simili restano la porta giusta quando un utente autorizza pubblicazione, messaggi, annunci o insight privati. MCP non aggiunge questi permessi.

SocQ MCP è una porta per i dati pubblici. Un agente può chiamare solo funzionalità già presenti nel catalogo API. Non può pubblicare, non può leggere account privati e non può inventare un endpoint che non è nel registro. REST, MCP e la CLI eseguono gli stessi job. La Agent Skill aiuta un agente a scegliere gli endpoint e a stimare i crediti; non è un secondo servizio di dati. Se il prodotto parla già HTTP, resta su REST. Se chi opera lavora in un terminale o in un job CI, usa la CLI. Se chi opera è un agente nell’IDE, usa MCP.

Scegli un ambito di strumenti, non un endpoint tirato a indovinare

Un client MCP vede solo gli strumenti esposti dalla connessione corrente. Scegli l’ambito su /mcp, poi copia l’indirizzo corrispondente.

AmbitoIndirizzoSuperficie visibileIdeale per
Compatto/mcpStrumenti di scoperta, esecuzione, attività, file e accountEsplorazione che può spostarsi tra più piattaforme
Piattaforme/mcp?platforms=youtube,tiktokStrumenti di raccolta tipizzati fino a cinque piattaforme, più strumenti per attività, file e accountAgenti che restano su un insieme noto di piattaforme
Strumenti esatti/mcp?tools=youtube_comments,x_searchFino a trenta strumenti tipizzati, più strumenti per attività, file e accountFlussi di lavoro stabili con un elenco di strumenti controllato

platforms e tools si escludono a vicenda. Dopo aver cambiato un filtro, ricollega il client in modo che aggiorni tools/list. Una connessione compatta che non viene mai ricollegata continuerà a servire l’elenco di strumenti precedente.

All’interno dell’ambito scegli comunque una funzionalità concreta del catalogo. La modalità compatta cerca nel registro. Le modalità per piattaforme e per strumenti esatti chiamano uno strumento tipizzato il cui schema di input corrisponde al body REST di quella risorsa.

Un’impostazione predefinita utile:

  • Parti dalla modalità compatta quando la domanda può passare dai commenti di YouTube alla ricerca su X e a una query su Shop.
  • Passa alla modalità per piattaforme quando l’agente lavora solo su due o tre reti.
  • Passa agli strumenti esatti quando una valutazione in produzione deve vedere un elenco di strumenti fisso.

Non mantenere una connessione a cinque piattaforme per poi chiedere al modello di “provare anche Amazon”. Ricollegati con Amazon nel filtro, oppure torna alla modalità compatta.

Collega un client e tieni la chiave fuori da Git

Esegui la configurazione in tre passaggi, allo stesso livello della pagina MCP:

  1. Scegli modalità compatta, piattaforme o strumenti esatti.
  2. Scegli Codex, Claude, Cursor o VS Code.
  3. Copia la configurazione generata e ricollega il client.

File dei client e trasporti:

ClientFile di configurazioneModalità di connessione
Codex~/.codex/config.tomlHTTP remoto verso l’URL Streamable HTTP ospitato
Claudeclaude_desktop_config.jsonBridge stdio @socq/mcp, Node.js 20+
Cursor.cursor/mcp.jsonBridge stdio @socq/mcp
VS Codemcp.jsonBridge stdio, con la chiave come input richiesto

La scoperta di piattaforme, endpoint e schemi non richiede una chiave. Raccolta, account, risultati delle attività e file sì. Conserva SOCQ_API_KEY nell’ambiente o nell’input protetto del client. Non committare la chiave.

Un esempio generico di Streamable HTTP si presenta così. Preferisci il file generato dalla pagina MCP per il tuo client; non aggiungere campi non documentati.

{
  "mcpServers": {
    "socq": {
      "url": "https://api.socq.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${SOCQ_API_KEY}"
      }
    }
  }
}

Codex si collega direttamente a quell’URL ospitato. Claude, Cursor e VS Code di norma lo raggiungono tramite il bridge @socq/mcp pubblicato. Dopo il salvataggio, riavvia o ricollega il server SocQ nel client.

REST e MCP condividono la stessa funzionalità

Ogni raccolta ha un percorso REST, un ID endpoint e il nome di uno strumento tipizzato. La modalità compatta inserisce i campi di business dentro input. Gli strumenti tipizzati espongono direttamente quello schema.

POST /v1/tiktok/profiles
  = endpoint id tiktok-profiles
  = typed tool tiktok_profiles

Fatturazione, limiti e struttura dell’attività non cambiano quando cambi porta. Gli strumenti di scoperta non creano job di raccolta. Se REST rifiuterebbe un elenco di username, lo rifiuterà anche MCP.

Invia una raccolta, poi interroga la stessa attività

La modalità compatta è un percorso a tre strumenti più la prosecuzione dell’attività:

natural-language request
  → socq_search_endpoints
  → socq_describe_endpoint
  → socq_execute(endpoint, input)
  → task_id
  → socq_get_task
  → results.items

socq_execute convalida l’input di business e crea una raccolta asincrona. Può attendere brevemente, poi restituisce lo stato corrente. Se l’attività è ancora queued o running, continua con lo stesso task_id. Un timeout del client non annulla la raccolta.

Quando l’attività riesce, leggi results.items. Finché has_more è true, passa next_cursor senza modificarlo. Non inviare di nuovo lo stesso profilo Instagram o lo stesso username TikTok solo perché la prima pagina era breve.

Le modalità per piattaforme e per strumenti esatti saltano la ricerca quando lo strumento tipizzato è già nel contesto. Il contratto dell’attività non cambia: crea una volta, salva l’ID, interroga, pagina.

Esempio di intento in modalità compatta, non uno screenshot di una chat:

Collect the public TikTok profile for @tiktok.
Describe the tiktok/profiles input first.
Execute, wait for the task, then return username, name, visible metrics, and collected_at.

L’agente dovrebbe tornare con un ID attività e con elementi normalizzati, non con l’affermazione che “il profilo è arrivato in un unico risultato sincrono dello strumento”.

Salva la stessa riga operativa che salveresti per REST:

  • ID dell’endpoint scelto o nome dello strumento tipizzato.
  • Input di business canonico.
  • ID attività.
  • Primo stato osservato e stato finale.
  • Ultimo next_cursor consumato.

Se il processo dell’agente si interrompe, riprendi quell’attività. Non lasciare che un ciclo di nuovi tentativi apra cinque job identici per lo stesso profilo TikTok.

L’igiene dell’input resta tua

MCP non allenta la convalida di REST.

  • L’input compatto deve corrispondere allo schema dell’endpoint restituito da socq_describe_endpoint.
  • Gli strumenti tipizzati espongono gli stessi campi obbligatori di POST /v1/{platform}/{resource}.
  • Rimuovi @ oppure mantienilo in modo coerente. Converti gli URL dei profili in username nel prompt o in un passaggio preliminare.
  • Non inviare l’URL di un video a un campo username, né un username a un campo URL di stato.
  • Considera results_limit un tetto. Il catalogo non promette completezza.
  • Se l’ambito ha escluso la piattaforma, ricollegati con un filtro di piattaforme o strumenti che la includa. Non chiedere al modello di “chiamare comunque TikTok”.

Scrivi nel tuo log l’ID dell’endpoint scelto, gli input e l’ID attività. Gli agenti dimenticano; la tua tabella dei job no.

Leggi i campi normalizzati, non la prosa della chat

Gli elementi riusciti usano la stessa struttura di REST: id, platform, resource, type, url, author, metrics, created_at, collected_at ed extra quando presente.

Chiedi all’agente di preservare i null. Un numero di follower nascosto non è zero. Una trascrizione mancante non significa “nessun parlato”. Gli URL dei media sono riferimenti alla fonte.

Se ti servono file, recuperali con lo strumento file per quell’attività. Se ti serve un’altra pagina, conserva il cursore. Se ti serve un’altra risorsa, descrivi ed esegui quella risorsa; non rimodellare il primo payload in un falso secondo schema.

Controlli minimi prima di fidarti di una riga riassunta dall’agente:

  • platform e resource corrispondono allo strumento eseguito.
  • Esiste almeno uno tra id e url.
  • Le metriche sono numeri o null, mai zeri forzati.
  • collected_at è presente e non è copiato in created_at.
  • La risposta in prosa è riconducibile a results.items, non alla memoria del modello.

Chiedi all’agente di citare i campi, non di “ripulire” i valori mancanti.

Frequenza di aggiornamento per gli agenti

Le connessioni MCP e i job di raccolta hanno ritmi diversi.

OggettoAbitudine sensataMotivo
Ambito degli strumentiRicollegarsi dopo ogni cambio di filtroI client mettono in cache tools/list
ScopertaRipetere socq_search_endpoints quando cambia la domandaIl catalogo è dinamico; il risultato precedente potrebbe essere la risorsa sbagliata
Attività di raccoltaInterrogare lo stesso IDReinviare duplica il lavoro
Entità di tipo profiloSettimanale o mensileI campi di identità cambiano lentamente
Post, commenti, annunci, prodottiDa ogni ora a ogni giorno, finché sono attiviMetriche pubbliche e inserzioni cambiano più in fretta
Server di produzione con strumenti esattiCambiare gli strumenti solo con un rilascio pianificatoElenchi di strumenti imprevisti rompono le valutazioni

Non aggiornare un’attività conclusa per “renderla sincrona”. Avvia una nuova attività solo quando gli input o la finestra temporale sono davvero cambiati.

Errori più comuni

L’agente dice che la piattaforma manca

La connessione corrente potrebbe essere limitata ad altre piattaforme o conservare ancora un vecchio tools/list. Apri /mcp, imposta l’ambito, copia la configurazione, ricollegati.

La raccolta viene rifiutata senza un profilo utile

La scoperta non richiede una chiave. L’esecuzione sì. Controlla SOCQ_API_KEY nell’ambiente o nell’input richiesto di VS Code.

La prima chiamata allo strumento è “finita” senza righe

Il job è asincrono. Leggi lo stato dell’attività. Continua con socq_get_task prima di ipotizzare un errore o di reinviare.

L’agente inventa uno strumento di pubblicazione o di dati privati

Quella funzionalità non è nel catalogo. Fermati. Usa un prodotto ufficiale con OAuth per le scritture e gli insight privati.

La paginazione si è fermata troppo presto

has_more e next_cursor fanno parte del risultato, non sono una decorazione facoltativa. Esaurisci il cursore oppure registra che ti sei fermato di proposito.

Il cambio di filtro non ha avuto effetto

platforms e tools non si possono combinare. Ricollegati dopo il cambio.

Uso responsabile

Raccogli solo i dati pubblici necessari per uno scopo legittimo. Non chiedere a un agente di aggirare account privati, accessi o controlli di accesso. Tieni le chiavi fuori dai prompt che incollerai nei ticket. Verifica i termini delle piattaforme e le tue regole di conservazione.

Non chiedere all’agente di:

  • Pubblicare, rispondere o inviare un DM.
  • Aprire una vista privata o con login.
  • Trattare socq_execute come un dataset completo.
  • Combinare platforms e tools nello stesso URL.
  • Inserire una chiave API reale in un file di configurazione committato.

SocQ MCP è una connessione tecnica. Non concede diritti aggiuntivi sui contenuti e non trasforma uno scraping non ufficiale in un’integrazione ufficiale.

Applica la stessa regola di minimizzazione dei dati che useresti in un worker REST: raccogli i campi pubblici richiesti dal ticket, poi fermati. Un agente con accesso compatto all’intero catalogo continuerà volentieri a scoprire endpoint che non hai chiesto. Gli ambiti vincolati esistono per questo.

Domande frequenti (FAQ)

SocQ MCP è una seconda API social?

No. È un’altra porta verso lo stesso catalogo usato da REST e dalla CLI.

Posso usarlo senza chiave API?

Puoi scoprire piattaforme, endpoint e schemi. Raccolta, account, risultati delle attività e file richiedono una chiave.

Perché la modalità compatta non elenca ogni API come strumento a sé?

La modalità compatta cerca e descrive un endpoint quando serve, così l’insieme completo degli schemi resta fuori dal contesto del modello.

Execute restituisce subito tutte le righe?

No. Restituisce un’attività. Continua quell’attività e scorri results.items pagina per pagina.

L’agente può pubblicare su X o leggere un account Instagram privato?

No. Può chiamare solo funzionalità pubbliche del catalogo.

Quando conviene aggiungere la Skill?

Quando l’agente deve scegliere gli endpoint e stimare i crediti in un job a più passaggi. MCP continua a eseguire. I dettagli sono su /skill.

Dove copio la configurazione reale del client?

Da /mcp: scegli l’ambito, scegli il client, copia, ricollegati.

MULTIPIATTAFORMA API

Prova il flusso di lavoro con un URL pubblico di Multipiattaforma

Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.

Scopri le API di Multipiattaforma