Documentazione API & MCP

Integra Simple Stickers con agenti AI, Claude e script di automazione

🔑

Autenticazione

Sia l'API REST che il server MCP utilizzano l'autenticazione tramite token Bearer attraverso una chiave API. Claude.ai (web, app desktop, mobile) accede invece al server MCP tramite OAuth — non devi generare né copiare alcuna chiave, vedi Connessione a Claude.ai.

Tipo di token Durata Come ottenerlo
ss_<40 caratteri esadecimali> — Chiave API Lunga durata — valida fino alla revoca Genera in Impostazioni Account → Scheda API
ss_… — chiave emessa tramite OAuth Lunga durata — valida fino alla revoca Creata automaticamente quando colleghi Claude.ai (nell'elenco delle chiavi con origine “App collegata”)

🔧 Generazione di una chiave API

  1. 1 Apri Simple Stickers e fai clic sul tuo avatar in alto a destra
  2. 2 Vai a Impostazioni Account → Scheda API
  3. 3 Fai clic su Genera chiave API, opzionalmente dagli un nome
  4. 4
    Copia la chiave immediatamente — viene mostrata solo una volta

    La chiave inizia con ss_ seguito da 40 caratteri esadecimali.

📤 Utilizzo del token

Passa il token in ogni richiesta come header Authorization Bearer:

Authorization: Bearer ss_a1b2c3d4e5f6...

Le chiavi API sono limitate all'utente che le ha create. Tutte le operazioni sui dati restituiscono solo i dati di quell'utente.

📡

API REST

🌐 Endpoint

POST https://www.simplestickers.app/api/agent Content-Type: application/json Authorization: Bearer <token>

📨 Corpo della richiesta

Tutte le azioni condividono lo stesso envelope JSON:

{ "action": "<action_name>", "<param>": "<value>" }

📬 Risposte

  • 200 OK Successo — dati JSON nel corpo
  • 4xx / 5xx Errore — {"error": "message"}
📁

Progetti

list_projects

Restituisce tutti i progetti appartenenti all'utente autenticato.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"list_projects"}'

Risposta: array di oggetti {"id","name","created_at"}.

find_project

Ricerca parziale del nome senza distinzione tra maiuscole e minuscole. Restituisce un array di progetti corrispondenti.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"find_project","name":"My Work"}'
ParametroTipoObbligatorio
namestringSì

create_project

Crea un nuovo progetto. Restituisce l'oggetto progetto creato.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"create_project","name":"Q3 Campaign"}'
ParametroTipoObbligatorio
namestringSì

rename_project

Rinomina un progetto esistente.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"rename_project","project_id":"<uuid>","name":"New Name"}'
ParametroTipoObbligatorio
project_idstring (UUID)Sì
namestringSì

delete_project

Elimina un progetto e tutte le sue attività (cascade). Restituisce {"success":true}.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"delete_project","project_id":"<uuid>"}'
⚠️ Irreversibile. Tutte le attività nel progetto vengono eliminate permanentemente.
📝

Attività

list_tasks

Restituisce le attività in un progetto, ordinate per posizione. Opzionalmente filtrate per stato.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"list_tasks","project_id":"<uuid>"}' # Filtra per stato: -d '{"action":"list_tasks","project_id":"<uuid>","status":"in_progress"}' # Modalità compatta senza note complete: -d '{"action":"list_tasks","project_id":"<uuid>","include_notes":false}'
ParametroTipoObbligatorioDescrizione
project_idstring (UUID)Sì
statusstringNoFiltra per valore di stato (vedi enum sotto)
include_notesbooleanNoCon false restituisce notes_preview (prima riga) e notes_chars invece delle note complete — risposta molto più piccola, ideale per i loop di orchestrazione

get_task

Restituisce una singola attività per ID, incluso il suo project_id.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"get_task","task_id":"<uuid>"}'

create_task

Crea una nuova attività in un progetto. Restituisce l'oggetto attività creato.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "action": "create_task", "project_id": "<uuid>", "text": "Write unit tests", "priority": true, "color": "yellow", "deadline": "2026-06-30", "notes": "## Context\n\n- Cover happy path\n- Cover edge cases" }'
ParametroTipoObbligatorioPredefinito
project_idstring (UUID)Sì
textstringSì
statusstringNobacklog
notesstring (Markdown)Nonull
prioritybooleanNofalse
colorstring | nullNonull (bianco)
deadlinestring (YYYY-MM-DD) | nullNonull
positionnumberNofine della colonna (max + 1000)

update_task

Aggiorna uno o più campi di un'attività esistente. Almeno un campo opzionale deve essere fornito.

# Sposta attività a in_progress: curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"update_task","task_id":"<uuid>","status":"in_progress"}' # Aggiorna più campi contemporaneamente: -d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'
ParametroTipoObbligatorio
task_idstring (UUID)Sì
textstringNo
statusstringNo
notesstring (Markdown) | nullNo
prioritybooleanNo
colorstring | nullNo
deadlinestring (YYYY-MM-DD) | nullNo
positionnumberNo

append_to_notes

Aggiunge testo alla fine delle note di un'attività senza reinviare le note esistenti. Il nuovo testo è separato da una riga vuota (se le note sono vuote, viene salvato solo il nuovo testo). L'operazione è atomica, quindi aggiunte simultanee non si sovrascrivono. Restituisce l'attività aggiornata.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"append_to_notes","task_id":"<uuid>","text":"## Risultati dei test\n\n- Tutto superato"}'
ParametroTipoObbligatorio
task_idstring (UUID)Sì
textstring (Markdown)Sì

delete_task

Elimina permanentemente un'attività. Restituisce {"success":true}.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"delete_task","task_id":"<uuid>"}'

📋 Valori Enum

status

  • backlog
  • in_progress
  • review
  • testing
  • done

color

  • yellow
  • green
  • blue
  • null (bianco)

deadline

stringa YYYY-MM-DD, oppure null per cancellare.

priority

true = priorità alta
false = normale

📄

Note Attività (Markdown)

Le note delle attività sono archiviate e trasmesse come stringhe Markdown semplici. Il frontend le visualizza tramite react-markdown. Scrivi e leggi sempre Markdown — non HTML.

Sintassi Risultato
**text**Grassetto
*text*Corsivo
~~text~~Barrato
## HeadingTitolo H2
### HeadingTitolo H3
- itemElenco puntato
1. itemElenco numerato
`code`Codice inline
```\ncode\n```Blocco di codice
> textCitazione
[text](url)Hyperlink

📋 Nota di esempio in create_task

"notes": "## Task overview\n\n- Requirement 1\n- Requirement 2\n\n**Important:** deadline is Friday\n\n[Design brief](https://example.com/brief)"
Note precedenti: Le note salvate prima della migrazione Markdown potrebbero contenere HTML. Il frontend le converte automaticamente al momento della visualizzazione. Durante la lettura tramite l'API, le note precedenti potrebbero restituire stringhe HTML — scrivi sempre Markdown, accetta HTML durante la lettura.
⚙️

Impostazioni

get_column_settings

Restituisce le impostazioni di visibilità delle colonne Kanban dell'utente.

curl -s -X POST https://www.simplestickers.app/api/agent \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"get_column_settings"}'

Risposta di esempio:

{ "columns": { "backlog": true, "in_progress": true, "review": false, "testing": false, "done": true } }

columns è null se l'utente non ha personalizzato la visibilità delle colonne (si applicano tutti i predefiniti).

❌

Riferimento Errori

Stato HTTP Valore error Significato
401 Unauthorized Token mancante, non valido o revocato. Il server MCP restituisce inoltre l'intestazione WWW-Authenticate con un link ai metadati OAuth.
400 Missing <param> Parametro obbligatorio non fornito
400 Unknown action Nome azione non riconosciuto
403 Key management requires JWT authentication Tentativo di gestire le chiavi con un token di chiave API
500 varia Errore server inaspettato
🤖

Integrazione MCP

Cos'è MCP?

MCP (Model Context Protocol) è uno standard che consente ai client AI (Claude Code, Claude Desktop, Cursor…) di connettersi a strumenti esterni. A differenza dell'API REST, il server MCP si descrive da solo — il client chiede quali strumenti esistono, poi li chiama direttamente senza bisogno di conoscere URL o formati di richiesta.

✅ Usa MCP quando…

  • • Vuoi che Claude gestisca i tuoi compiti in modo conversazionale
  • • Hai bisogno che l'AI scopra da sola le operazioni disponibili
  • • Preferisci un'integrazione plug-and-play con Claude Code / Claude Desktop
  • • Vuoi usare il linguaggio naturale invece di scrivere comandi curl

📡 Usa API REST quando…

  • • Stai costruendo i tuoi script di automazione o pipeline CI
  • • Hai bisogno di un controllo granulare sulle richieste HTTP
  • • Stai integrando con sistemi che non supportano MCP
  • • Vuoi elaborare le risposte a livello di programmazione

🛠️ Strumenti MCP Disponibili

list_projects

find_project

create_project

rename_project

delete_project

get_column_settings
list_tasks

get_task

create_task

update_task

append_to_notes

delete_task
Endpoint MCP: https://www.simplestickers.app/api/mcp (Trasporto HTTP Streamable, JSON-RPC 2.0)

🔌 Come connettersi

  • • Claude.ai — web, app desktop, mobile: connettore personalizzato con accesso tramite OAuth, senza chiave API — guida
  • • Claude Code: configurazione con chiave API nell'intestazione, oppure accesso tramite OAuth — guida
  • • n8n e altri strumenti: client HTTP MCP con l'intestazione Authorization: Bearer ss_… (chiave da Impostazioni Account → Scheda API)
☁️

Connessione a Claude.ai

Aggiungi Simple Stickers come connettore personalizzato in Claude. Accedi con il tuo account Simple Stickers e consenti l'accesso — non devi generare né incollare alcuna chiave API. Il connettore funziona poi in Claude sul web, nell'app desktop e su mobile.

🔗 Procedura

  1. 1 In Claude apri Settings → Connectors e fai clic su Add custom connector
  2. 2
    Inserisci un nome qualsiasi (ad es. Simple Stickers) e l'URL del server:
    https://www.simplestickers.app/api/mcp
  3. 3 Fai clic su Connect — si aprirà la pagina di Simple Stickers
  4. 4 Accedi (con e-mail o tramite Google) e fai clic su Consenti. Tornerai in Claude con il connettore collegato.

✅ Cosa succede dopo

  • • Il connettore si sincronizza con l'app desktop di Claude e con il mobile — lo configuri una sola volta
  • • Nella conversazione basta scrivere ad esempio “Quali attività ho nel progetto Web?”
  • • Claude ha il tuo stesso accesso: vede, crea, modifica ed elimina i tuoi progetti e le tue attività

🔌 Disconnessione

  • • In Simple Stickers apri Impostazioni Account → Scheda API
  • • Revoca la chiave con origine App collegata (nome “Claude”) con il pulsante Revoca
  • • Da quel momento Claude non ha più accesso al tuo account; per ricollegarlo basta fare di nuovo clic su Connect in Claude
Nei piani Team / Enterprise di Claude solo il proprietario dell'organizzazione può aggiungere connettori personalizzati; gli altri membri si collegano poi semplicemente con il proprio account.
💻

Configurazione Claude Code

Claude Code supporta nativamente i server HTTP MCP — nessun proxy necessario. Configura una volta globalmente o per progetto.

🔐 Il modo più semplice: accesso tramite OAuth (senza chiave API)

Aggiungi il server senza intestazione e poi accedi con il comando /mcp → simplestickers → Authenticate. Si aprirà il browser con la stessa pagina di consenso di Claude.ai.

claude mcp add --transport http simplestickers https://www.simplestickers.app/api/mcp

Per script e configurazioni condivise puoi continuare a usare la chiave API nell'intestazione — vedi sotto.

🌐 Configurazione globale — ~/.claude/mcp.json

Si applica a tutte le sessioni di Claude Code sulla tua macchina:

{ "mcpServers": { "simplestickers": { "type": "http", "url": "https://www.simplestickers.app/api/mcp", "headers": { "Authorization": "Bearer ss_your_api_key_here" } } } }

📁 Configurazione per progetto — .mcp.json nella radice del progetto

Stesso formato della configurazione globale — si applica solo quando lavori all'interno di quella directory:

{ "mcpServers": { "simplestickers": { "type": "http", "url": "https://www.simplestickers.app/api/mcp", "headers": { "Authorization": "Bearer ss_your_api_key_here" } } } }

✅ Verifica la connessione

Dopo aver salvato la configurazione, apri Claude Code e digita:

/mcp

Dovresti vedere simplestickers elencato con tutti i 12 strumenti disponibili. Se il server è disconnesso, fai clic su Riconnetti.

🖥️

Configurazione Claude Desktop

Consigliato: il modo più semplice è aggiungere Simple Stickers come connettore in Claude.ai — comparirà automaticamente anche in Claude Desktop e su mobile, senza file di configurazione né chiave API. Vedi Connessione a Claude.ai. La configurazione manuale qui sotto è un'alternativa per l'installazione locale con chiave API.
Importante: Claude Desktop non supporta il trasporto HTTP MCP direttamente — utilizza solo il trasporto stdio. Usa mcp-remote come proxy. Il flag -y approva automaticamente l'installazione npm senza richieste interattive.

🍎 macOS

File di configurazione: ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "simplestickers": { "command": "npx", "args": [ "-y", "mcp-remote", "https://www.simplestickers.app/api/mcp", "--header", "Authorization: Bearer ss_your_api_key_here" ] } } }

🪟 Windows

File di configurazione: %APPDATA%\Claude\claude_desktop_config.json

(di solito C:\Users\<name>\AppData\Roaming\Claude\claude_desktop_config.json)

Su Windows, Claude Desktop avvia i processi senza un contesto di shell, quindi npx deve essere racchiuso in cmd /c:

{ "mcpServers": { "simplestickers": { "command": "cmd", "args": [ "/c", "npx", "-y", "mcp-remote", "https://www.simplestickers.app/api/mcp", "--header", "Authorization: Bearer ss_your_api_key_here" ] } } }
Dopo aver modificato la configurazione, riavvia Claude Desktop. Dovresti vedere gli strumenti Simple Stickers apparire nell'elenco degli strumenti all'interno di una conversazione.
💡

Esempi Rapidi

📡 Flusso di lavoro REST completo — trova progetto → crea attività → aggiorna stato

BASE="https://www.simplestickers.app/api/agent" TOKEN="ss_your_api_key_here" # 1. Trova il progetto curl -s -X POST $BASE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"find_project","name":"My Work"}' # 2. Crea un'attività (usa project_id dal passo 1) curl -s -X POST $BASE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "action": "create_task", "project_id": "<project-uuid>", "text": "Write unit tests", "priority": true, "color": "yellow" }' # 3. Sposta l'attività a in_progress (usa task id dal passo 2) curl -s -X POST $BASE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "action": "update_task", "task_id": "<task-uuid>", "status": "in_progress" }' # 4. Segna come completato curl -s -X POST $BASE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"action":"update_task","task_id":"<task-uuid>","status":"done"}'

🤖 Flusso di lavoro MCP in Claude Code

Una volta configurato il server MCP, puoi parlare con Claude in modo naturale:

Tu: Trova il mio progetto "Website Redesign" ed elenca tutte le attività che sono in_progress
Tu: Crea un'attività ad alta priorità "Fix mobile navigation" con scadenza 2026-06-30 e aggiungi note con una checklist
Tu: Sposta tutte le attività denominate "Deploy *" nello stato completato

Claude usa automaticamente gli strumenti MCP in base alle tue istruzioni in linguaggio naturale.

🔬 Testa il server MCP direttamente con curl

BASE="https://www.simplestickers.app/api/mcp" TOKEN="ss_your_api_key_here" # Without a token → HTTP 401 + WWW-Authenticate (OAuth discovery) curl -s -i -X POST $BASE -H "Content-Type: application/json" -d '{}' # Handshake curl -s -X POST $BASE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}},"id":1}' # Elenca gli strumenti curl -s -X POST $BASE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}' # Chiama uno strumento curl -s -X POST $BASE \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"list_projects","arguments":{}},"id":3}'