Panoramica di MCP

Il Model Context Protocol (MCP) è uno standard aperto che permette a un client IA di chiamare strumenti su un server remoto. Il server MCP di StickyPrompts espone il tuo workspace sotto forma di strumenti: cercare in una knowledge base, eseguire un prompt salvato, trovare un contatto nel CRM, interrogare un database collegato, inviare un’email, generare un’immagine. Collegalo una volta e il tuo assistente potrà svolgere lavoro concreto, con gli stessi modelli, gli stessi dati e le stesse regole che il tuo team usa nell’app.

Tutorial 13 di 14 · 1:48 The MCP server Video in inglese, registrato nell'app reale

In sintesi

Endpoint	https://api.stickyprompts.com/mcp/
Trasporto	Solo Streamable HTTP. Non esistono un endpoint legacy /sse né un server stdio.
Autenticazione	Authorization: Bearer STICKY-API-..., la stessa chiave API dell’API REST
Funzionalità	Solo strumenti. Niente resource, resource template o prompt MCP.
Nome del server	StickyPrompts, versione 1.0.0 (riportato in initialize)

Usa la barra finale

L’endpoint è /mcp/ con la barra finale. Una richiesta a /mcp viene reindirizzata a /mcp/ (301 per GET, 307 per POST e DELETE). La maggior parte dei client segue il redirect, ma configura direttamente https://api.stickyprompts.com/mcp/: risparmi un passaggio e funziona anche con i client che non seguono i redirect.

Autenticazione

Invia la tua chiave API nell’header Authorization, esattamente come per REST. Le chiavi si creano in Settings > API keys; consulta Chiavi API e autenticazione.

Situazione	Risposta HTTP
Nessun header Authorization, o un token che non è Bearer STICKY-API-...	401 {"error":"unauthorized"}
Chiave sconosciuta, segreto errato o proprietario della chiave non più esistente	401 {"error":"Invalid API key"}
L’account del proprietario della chiave non è attivo	403 {"error":"user is not verified"}
La richiesta proviene da una regione non servita dal servizio	403 {"error":"access from your region is not supported"}

Per connettersi non serve alcuna autorizzazione particolare. Qualsiasi chiave valida di un account attivo può aprire una sessione: cosa può fare dopo viene deciso strumento per strumento.

La chiave agisce come l’utente che l’ha creata: stesso workspace, stessi progetti, stesse risorse condivise, entro i limiti delle autorizzazioni della chiave. Tutto ciò che crei via MCP (conversazioni, progetti, file generati) è tuo e compare nell’app.

Sessioni

Il server usa le sessioni standard di Streamable HTTP. I client MCP gestiscono tutto in automatico; questi dettagli contano solo se implementi il protocollo a mano.

• Un POST /mcp/ con una richiesta initialize restituisce un id di sessione nell’header di risposta Mcp-Session-Id (formato mcp-session-<uuid>).
• Ogni POST successivo deve inviare quell’header Mcp-Session-Id. Un id mancante o malformato riceve 404 Invalid session ID.
• Le sessioni sono stateless lato server: viene controllato solo il formato dell’id. Sopravvivono ai riavvii del server, quindi non devi riconnetterti dopo un deploy.
• POST richiede Content-Type: application/json. In pratica le risposte sono in JSON, perché nessuno strumento invia notifiche di avanzamento.
• GET /mcp/ apre un flusso di notifiche facoltativo, che resta quasi sempre inattivo. DELETE /mcp/ viene accettato e non fa nulla.

Le autorizzazioni decidono quali strumenti vedi

Ogni strumento richiede esattamente un’autorizzazione. Il server filtra sia tools/list sia tools/call in base alle autorizzazioni della chiave:

• Una chiave vede solo gli strumenti per cui possiede l’autorizzazione. Una chiave senza autorizzazioni rilevanti per MCP si connette senza problemi e vede un elenco di strumenti vuoto.
• Chiamare uno strumento che la chiave non può usare restituisce l’errore JSON-RPC -32602 con tool '<name>' not found, esattamente come chiamare uno strumento che non esiste.

Quindi, se il tuo client segnala che manca uno strumento di StickyPrompts, controlla prima le autorizzazioni della chiave. Le autorizzazioni con il badge MCP nel riferimento delle autorizzazioni sono quelle che sbloccano strumenti, e ogni voce del riferimento degli strumenti indica la sua autorizzazione.

Qui il principio del privilegio minimo conta più del solito: un client IA userà ogni strumento che vede. A una chiave destinata a un assistente concedi solo gli strumenti che sei disposto a fargli chiamare, e lascia disattivati gli strumenti di scrittura come send_email o run_database_query se non ti servono.

Risultati ed errori

Ogni strumento restituisce un unico elemento di contenuto testuale, il cui testo è un documento JSON. Interpreta il testo come JSON. Non ci sono structuredContent né schemi di output; la forma di ogni risultato è documentata nel riferimento degli strumenti.

{
  "content": [
    { "type": "text", "text": "{\"conversation_id\": 5120, \"text\": \"Here are three options ...\"}" }
  ]
}

Gli errori tornano in uno di due modi:

Tipo	Aspetto	Usato per
Errore dello strumento	Un risultato con isError: true e un messaggio semplice, come conversation not found	Molte ricerche del tipo «non trovato o senza accesso»
Errore JSON-RPC -32603	Una chiamata fallita che riporta il messaggio del server, come required argument "prompt" not found	Argomenti obbligatori mancanti, la maggior parte degli errori di validazione, errori dei provider e delle integrazioni

Gli schemi di input vengono comunicati al tuo client ma non sono validati dal server, quindi un argomento del tipo sbagliato si manifesta con uno degli errori qui sopra, non con un errore di schema.

Strumenti di lunga durata

La maggior parte degli strumenti è sincrona: risponde quando il lavoro è finito. Alcuni rispondono subito e vanno interrogati con il polling.

Avvia con	Restituisce	Polling con	Finito quando
generate_video	{"id", "status"}	get_video_generation_status	status vale done o error
start_spreadsheet_processing	{"task_id"}	get_spreadsheet_processing_task	status vale done o error
run_workflow_task	{"execution_id", "status"}	Nessuno strumento di stato via MCP	Controlla in seguito total_run_count e success_rate con get_workflow_task

Un video può richiedere diversi minuti; la descrizione stessa dello strumento chiede al modello di attendere 15-60 secondi tra un polling e l’altro. generate_speech, generate_music e transcribe sono sincroni: restano in attesa finché l’audio o la trascrizione non sono pronti. Per questi strumenti, e per send_message con un modello lento, imposta nel tuo client un timeout delle richieste generoso.

Crediti e regole di accesso

• Gli strumenti che svolgono lavoro effettivo - send_message, run_prompt, custom_run, gli strumenti per i media, search_knowledge_base, l’elaborazione dei fogli di calcolo e le esecuzioni dei workflow - vengono conteggiati sull’account del proprietario della chiave, come le stesse azioni nell’app.
• Un workflow avviato con run_workflow_task fallisce con quota exceeded se il proprietario ha esaurito la quota.
• Le regole di accesso ai modelli e i filtri di residenza dei dati si applicano quando viene risolto il modello. Se il tuo workspace non consente un modello, la chiamata fallisce. list_ai_models esclude già i modelli che non puoi usare.

Scegliere un modello

run_prompt, custom_run e start_spreadsheet_processing richiedono un ai_model_id ottenuto da list_ai_models. Non esiste un valore "auto". send_message accetta un ai_model_id facoltativo, ma passalo sempre quando avvii una nuova conversazione: senza, al momento la chiamata fallisce con no AI model is selected, try reselecting model. Gli strumenti per i media non accettano argomenti sul modello.

Cosa non fa il server MCP

• Nessun caricamento di file. Importa i file da Google Drive con import_storage_files, oppure caricali tramite l’API REST.
• Nessun link di download per file arbitrari. list_files e get_file restituiscono solo id, nome e tipo. I risultati dei media includono un path al file salvato.
• Niente resource né prompt MCP. Ai tuoi prompt salvati accedi tramite gli strumenti list_prompts, get_prompt e run_prompt.
• Niente OAuth. I client che possono aggiungere server remoti solo tramite un accesso OAuth non riescono a connettersi con una chiave API.