Documentation de l'API et du serveur MCP de Simple Stickers

🔑

Authentification

L'API REST et le serveur MCP utilisent l'authentification par jeton Bearer via une clé API.

Type de jeton	Durée de vie	Comment l'obtenir
`ss_<40 hex chars>` — Clé API	Longue durée — valide jusqu'à révocation	Générez dans Paramètres du compte → Onglet API

🔧 Génération d'une clé API

1 Ouvrez Simple Stickers et cliquez sur votre avatar en haut à droite
2 Allez à Paramètres du compte → Onglet API
3 Cliquez sur Générer une clé API, donnez-lui optionnellement un nom
4
Copiez la clé immédiatement — elle ne s'affiche qu'une fois
La clé commence par ss_ suivi de 40 caractères hexadécimaux.

📤 Utilisation du jeton

Passez le jeton dans chaque requête en tant qu'en-tête d'autorisation Bearer :

Authorization: Bearer ss_a1b2c3d4e5f6...

Les clés API sont limitées à l'utilisateur qui les a créées. Toutes les opérations de données renvoient uniquement les données de cet utilisateur.

📡

API REST

🌐 Point de terminaison

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

📨 Corps de la requête

Toutes les actions partagent la même enveloppe JSON :

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

📬 Réponses

200 OK Succès — Données JSON dans le corps
4xx / 5xx Erreur — {"error": "message"}

📁

Projets

list_projects

Retourne tous les projets appartenant à l'utilisateur authentifié.

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

Réponse : tableau d'objets {"id","name","created_at"}.

find_project

Recherche de nom partielle insensible à la casse. Retourne un tableau de projets correspondants.

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

Paramètre	Type	Requis
`name`	string	Oui

create_project

Crée un nouveau projet. Retourne l'objet projet créé.

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

Paramètre	Type	Requis
`name`	string	Oui

rename_project

Renomme un projet existant.

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

Paramètre	Type	Requis
`project_id`	string (UUID)	Oui
`name`	string	Oui

delete_project

Supprime un projet et toutes ses tâches (cascade). Retourne {"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>"}'

⚠️ Irréversible. Toutes les tâches du projet sont définitivement supprimées.

📝

Tâches

list_tasks

Retourne les tâches d'un projet, ordonnées par position. Optionnellement filtrées par statut.

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

# Filtrer par statut :
-d '{"action":"list_tasks","project_id":"<uuid>","status":"in_progress"}'

Paramètre	Type	Requis	Description
`project_id`	string (UUID)	Oui
`status`	string	Non	Filtrer par valeur de statut (voir enum ci-dessous)

get_task

Retourne une tâche unique par ID, y compris son 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

Crée une nouvelle tâche dans un projet. Retourne l'objet tâche créé.

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

Paramètre	Type	Requis	Par défaut
`project_id`	string (UUID)	Oui
`text`	string	Oui
`status`	string	Non	`backlog`
`notes`	string (Markdown)	Non	`null`
`priority`	boolean	Non	`false`
`color`	string \| null	Non	`null` (blanc)
`deadline`	string (YYYY-MM-DD) \| null	Non	`null`

update_task

Met à jour un ou plusieurs champs d'une tâche existante. Au moins un champ optionnel doit être fourni.

# Déplacer la tâche en cours de travail :
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"}'

# Mettre à jour plusieurs champs à la fois :
-d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'

Paramètre	Type	Requis
`task_id`	string (UUID)	Oui
`text`	string	Non
`status`	string	Non
`notes`	string (Markdown) \| null	Non
`priority`	boolean	Non
`color`	string \| null	Non
`deadline`	string (YYYY-MM-DD) \| null	Non

delete_task

Supprime définitivement une tâche. Retourne {"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>"}'

📋 Valeurs enum

status

backlog
in_progress
review
testing
done

color

yellow
green
blue
null (blanc)

deadline

Chaîne YYYY-MM-DD, ou null pour effacer.

priority

true = priorité haute
false = normal

📄

Notes de tâche (Markdown)

Les notes de tâche sont stockées et transmises en tant que chaînes Markdown brutes. Le frontend les rend via react-markdown. Écrivez toujours et lisez du Markdown — pas du HTML.

Syntaxe	Résultat
`text`	Gras
`text`	Italique
`~~text~~`	~~Barré~~
`## Heading`	En-tête H2
`### Heading`	En-tête H3
`- item`	Liste à puces
`1. item`	Liste numérotée
`code`	Code en ligne
```\ncode\n```	Bloc de code
`> text`	Citation
`[text](url)`	Lien hypertexte

📋 Exemple de note dans 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)"

Notes héritées : Les notes enregistrées avant la migration Markdown peuvent contenir du HTML. Le frontend les convertit automatiquement à l'affichage. Lors de la lecture via l'API, les anciennes notes peuvent renvoyer des chaînes HTML — écrivez toujours du Markdown, soyez tolérant à la lecture.

⚙️

Paramètres

get_column_settings

Retourne les paramètres de visibilité des colonnes Kanban de l'utilisateur.

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

Exemple de réponse :

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

columns est null si l'utilisateur n'a pas personnalisé la visibilité des colonnes (tous les paramètres par défaut s'appliquent).

❌

Référence des erreurs

Statut HTTP	Valeur d'`error`	Signification
401	`Unauthorized`	Jeton manquant ou invalide
400	`Missing <param>`	Paramètre obligatoire non fourni
400	`Unknown action`	Nom d'action non reconnu
403	`Key management requires JWT authentication`	Tentative de gérer les clés avec un jeton clé API
500	varie	Erreur serveur inattendue

🤖

Intégration MCP

Qu'est-ce que MCP ?

MCP (Model Context Protocol) est une norme qui permet aux clients d'IA (Claude Code, Claude Desktop, Cursor…) de se connecter à des outils externes. Contrairement à l'API REST, le serveur MCP se décrit lui-même — le client demande quels outils existent, puis les appelle directement sans avoir besoin de connaître les URL ou les formats de requête.

✅ Utilisez MCP quand…

• Vous voulez que Claude gère vos tâches de manière conversationnelle
• Vous avez besoin que l'IA découvre les opérations disponibles par elle-même
• Vous préférez une intégration prête à l'emploi avec Claude Code / Claude Desktop
• Vous voulez utiliser le langage naturel au lieu d'écrire des commandes curl

📡 Utilisez l'API REST quand…

• Vous créez vos propres scripts d'automatisation ou pipelines CI
• Vous avez besoin d'un contrôle précis sur les requêtes HTTP
• Vous intégrez avec des systèmes qui ne supportent pas MCP
• Vous voulez traiter les réponses de manière programmatique

🛠️ Outils MCP disponibles

list_projects

find_project

create_project

rename_project

delete_project

get_column_settings

list_tasks

get_task

create_task

update_task

delete_task

Point de terminaison MCP : https://www.simplestickers.app/api/mcp (Transport HTTP en streaming, JSON-RPC 2.0)

💻

Configuration de Claude Code

Claude Code supporte nativement les serveurs MCP HTTP — aucun proxy nécessaire. Configurez une seule fois globalement ou par projet.

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

S'applique à toutes les sessions Claude Code sur votre machine :

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

📁 Configuration par projet — .mcp.json à la racine du projet

Même format que la configuration globale — s'applique uniquement lors du travail dans ce répertoire :

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

✅ Vérifiez la connexion

Après avoir enregistré la configuration, ouvrez Claude Code et tapez :

/mcp

Vous devriez voir simplestickers listé avec les 11 outils disponibles. Si le serveur apparaît comme déconnecté, cliquez sur Reconnect.

🖥️

Configuration de Claude Desktop

Important : Claude Desktop ne supporte pas le transport MCP HTTP directement — il utilise uniquement le transport stdio. Utilisez mcp-remote comme proxy. Le drapeau -y approuve automatiquement l'installation npm sans invite interactive.

🍎 macOS

Fichier de configuration : ~/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

Fichier de configuration : %APPDATA%\Claude\claude_desktop_config.json

(généralement C:\Users\<name>\AppData\Roaming\Claude\claude_desktop_config.json)

Sur Windows, Claude Desktop lance les processus sans contexte shell, donc npx doit être enveloppé dans 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"
      ]
    }
  }
}

Après avoir édité la configuration, redémarrez Claude Desktop. Vous devriez voir les outils Simple Stickers apparaître dans la liste des outils à l'intérieur d'une conversation.

💡

Exemples rapides

📡 Flux complet REST — trouver un projet → créer une tâche → mettre à jour le statut

BASE="https://www.simplestickers.app/api/agent"
TOKEN="ss_your_api_key_here"

# 1. Trouver le projet
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"find_project","name":"My Work"}'

# 2. Créer une tâche (utiliser project_id de l'étape 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. Déplacer la tâche en cours de travail (utiliser id de tâche de l'étape 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. Marquer comme terminé
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<task-uuid>","status":"done"}'

🤖 Flux MCP dans Claude Code

Une fois le serveur MCP configuré, vous pouvez parler à Claude naturellement :

Vous : Trouvez mon projet "Website Redesign" et listez toutes les tâches en cours de travail

Vous : Créez une tâche de haute priorité "Fix mobile navigation" avec une date limite de 2026-06-30 et ajoutez des notes avec une liste de contrôle

Vous : Déplacez toutes les tâches nommées "Deploy *" au statut terminé

Claude utilise automatiquement les outils MCP en fonction de vos instructions en langage naturel.

🔬 Testez directement le serveur MCP avec curl

BASE="https://www.simplestickers.app/api/mcp"
TOKEN="ss_your_api_key_here"

# Poignée de main (aucune authentification requise)
curl -s -X POST $BASE \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}},"id":1}'

# Lister les outils
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

# Appeler un outil
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}'