Documentazione API e MCP di Simple Stickers

🔑

Autenticazione

Sia l'API REST che il server MCP utilizzano l'autenticazione tramite token Bearer attraverso una chiave API.

Tipo di token	Durata	Come ottenerlo
`ss_<40 caratteri esadecimali>` — Chiave API	Lunga durata — valida fino alla revoca	Genera in Impostazioni Account → Scheda API

🔧 Generazione di una chiave API

1 Apri Simple Stickers e fai clic sul tuo avatar in alto a destra
2 Vai a Impostazioni Account → Scheda API
3 Fai clic su Genera chiave API, opzionalmente dagli un nome
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"}'

Parametro	Tipo	Obbligatorio
`name`	string	Sì

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"}'

Parametro	Tipo	Obbligatorio
`name`	string	Sì

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"}'

Parametro	Tipo	Obbligatorio
`project_id`	string (UUID)	Sì
`name`	string	Sì

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"}'

Parametro	Tipo	Obbligatorio	Descrizione
`project_id`	string (UUID)	Sì
`status`	string	No	Filtra per valore di stato (vedi enum sotto)

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"
  }'

Parametro	Tipo	Obbligatorio	Predefinito
`project_id`	string (UUID)	Sì
`text`	string	Sì
`status`	string	No	`backlog`
`notes`	string (Markdown)	No	`null`
`priority`	boolean	No	`false`
`color`	string \| null	No	`null` (bianco)
`deadline`	string (YYYY-MM-DD) \| null	No	`null`

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}'

Parametro	Tipo	Obbligatorio
`task_id`	string (UUID)	Sì
`text`	string	No
`status`	string	No
`notes`	string (Markdown) \| null	No
`priority`	boolean	No
`color`	string \| null	No
`deadline`	string (YYYY-MM-DD) \| null	No

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~~
`## Heading`	Titolo H2
`### Heading`	Titolo H3
`- item`	Elenco puntato
`1. item`	Elenco numerato
`code`	Codice inline
```\ncode\n```	Blocco di codice
`> text`	Citazione
`[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 o non valido
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

delete_task

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

💻

Configurazione Claude Code

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

🌐 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 11 strumenti disponibili. Se il server è disconnesso, fai clic su Riconnetti.

🖥️

Configurazione Claude Desktop

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"

# Handshake (non è necessaria l'autenticazione)
curl -s -X POST $BASE \
  -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}'