Simple Stickers API & MCP Documentatie

🔑

Authenticatie

Zowel de REST API als MCP server gebruiken Bearer token authenticatie via een API-sleutel.

Tokentype	Levensduur	Hoe verkrijgen
`ss_<40 hex chars>` — API-sleutel	Langdurig — geldig tot ingetrokken	Genereer in Accountinstellingen → API-tabblad

🔧 Een API-sleutel genereren

1 Open Simple Stickers en klik op je avatar in de rechterbovenhoek
2 Ga naar Accountinstellingen → API tabblad
3 Klik op API-sleutel genereren, geef het optioneel een naam
4
Kopieer de sleutel onmiddellijk — deze wordt slechts eenmaal weergegeven
De sleutel begint met ss_ gevolgd door 40 hexadecimale tekens.

📤 De token gebruiken

Voeg de token in elk verzoek toe als Bearer Authorization header:

Authorization: Bearer ss_a1b2c3d4e5f6...

API-sleutels zijn beperkt tot de gebruiker die deze heeft gemaakt. Alle gegevensbewerkingen retourneren alleen gegevens van die gebruiker.

📡

REST API

🌐 Eindpunt

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

📨 Verzoekbody

Alle acties delen dezelfde JSON-omhulling:

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

📬 Reacties

200 OK Succes — JSON-gegevens in body
4xx / 5xx Fout — {"error": "message"}

📁

Projecten

list_projects

Retourneert alle projecten van de geverifieerde gebruiker.

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

Reactie: array van {"id","name","created_at"} objecten.

find_project

Niet-hoofdlettergevoelige gedeeltelijke naamzoeking. Retourneert een array van overeenkomende projecten.

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

Parameter	Type	Vereist
`name`	string	Ja

create_project

Maakt een nieuw project aan. Retourneert het gemaakte projectobject.

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

Parameter	Type	Vereist
`name`	string	Ja

rename_project

Wijzigt de naam van een bestaand project.

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

Parameter	Type	Vereist
`project_id`	string (UUID)	Ja
`name`	string	Ja

delete_project

Verwijdert een project en alle taken (waterval). Retourneert {"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>"}'

⚠️ Niet terug te draaien. Alle taken in het project worden permanent verwijderd.

📝

Taken

list_tasks

Retourneert taken in een project, geordend op positie. Optioneel gefilterd op status.

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

# Filter op status:
-d '{"action":"list_tasks","project_id":"<uuid>","status":"in_progress"}'

Parameter	Type	Vereist	Beschrijving
`project_id`	string (UUID)	Ja
`status`	string	Nee	Filter op statuswaarde (zie enum hieronder)

get_task

Retourneert een enkele taak op ID, inclusief de 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

Maakt een nieuwe taak in een project. Retourneert het gemaakte taakobject.

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

Parameter	Type	Vereist	Standaard
`project_id`	string (UUID)	Ja
`text`	string	Ja
`status`	string	Nee	`backlog`
`notes`	string (Markdown)	Nee	`null`
`priority`	boolean	Nee	`false`
`color`	string \| null	Nee	`null` (wit)
`deadline`	string (YYYY-MM-DD) \| null	Nee	`null`

update_task

Werkt een of meer velden van een bestaande taak bij. Minstens één optioneel veld moet worden verstrekt.

# Verplaats taak naar 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"}'

# Update meerdere velden tegelijk:
-d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'

Parameter	Type	Vereist
`task_id`	string (UUID)	Ja
`text`	string	Nee
`status`	string	Nee
`notes`	string (Markdown) \| null	Nee
`priority`	boolean	Nee
`color`	string \| null	Nee
`deadline`	string (YYYY-MM-DD) \| null	Nee

delete_task

Verwijdert een taak permanent. Retourneert {"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>"}'

📋 Enumwaarden

status

backlog
in_progress
review
testing
done

color

yellow
green
blue
null (wit)

deadline

YYYY-MM-DD string, of null om te wissen.

priority

true = hoge prioriteit
false = normaal

📄

Taak Notities (Markdown)

Taaknotities worden opgeslagen en verzonden als platte Markdown-strings. De frontend rendert deze via react-markdown. Schrijf en lees altijd Markdown — geen HTML.

Syntaxis	Resultaat
`text`	Vet
`text`	Cursief
`~~text~~`	~~Doorgestreept~~
`## Heading`	H2 kop
`### Heading`	H3 kop
`- item`	Opsomming
`1. item`	Genummerde lijst
`code`	Inlinegebruikscode
```\ncode\n```	Codeblok
`> text`	Citaatblok
`[text](url)`	Hyperlink

📋 Voorbeeld notitie 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)"

Verouderde notities: Notities die voor de Markdown-migratie zijn opgeslagen, kunnen HTML bevatten. De frontend zet ze automatisch om bij weergave. Bij het lezen via de API kunnen oude notities HTML-strings retourneren — schrijf altijd Markdown, wees tolerant bij het lezen.

⚙️

Instellingen

get_column_settings

Retourneert de instellingen voor zichtbaarheid van de Kanban-kolom van de gebruiker.

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

Voorbeeld reactie:

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

columns is null als de gebruiker de kolom zichtbaarheid niet heeft aangepast (alle standaardinstellingen gelden).

❌

Foutverwijzing

HTTP-status	`error` waarde	Betekenis
401	`Unauthorized`	Token ontbreekt of is ongeldig
400	`Missing <param>`	Vereiste parameter niet opgegeven
400	`Unknown action`	Actienaam niet herkend
403	`Key management requires JWT authentication`	Probeerde sleutels te beheren met een API-sleuteltoken
500	varieert	Onverwachte serverfout

🤖

MCP Integratie

Wat is MCP?

MCP (Model Context Protocol) is een standaard die AI-clients (Claude Code, Claude Desktop, Cursor…) laat verbinding maken met externe tools. In tegenstelling tot de REST API beschrijft de MCP server zichzelf — de client vraagt welke tools bestaan, en roept ze vervolgens rechtstreeks aan zonder URL's of verzoekindelingen te hoeven kennen.

✅ Gebruik MCP wanneer…

• Je Claude je taken conversationeel laat beheren
• Je nodig hebt dat de AI beschikbare bewerkingen zelf ontdekt
• Je een plug-and-play integratie met Claude Code / Claude Desktop prefereert
• Je liever natuurlijke taal gebruikt in plaats van curl-commando's

📡 Gebruik REST API wanneer…

• Je je eigen automatiseringsscripts of CI-pijplijnen bouwt
• Je fijnmazig beheer over HTTP-verzoeken nodig hebt
• Je integreert met systemen die MCP niet ondersteunen
• Je reacties programmatisch wilt verwerken

🛠️ Beschikbare MCP-tools

list_projects

find_project

create_project

rename_project

delete_project

get_column_settings

list_tasks

get_task

create_task

update_task

delete_task

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

💻

Claude Code Instellingen

Claude Code ondersteunt HTTP MCP-servers inheems — geen proxy nodig. Configureer eenmaal globaal of per project.

🌐 Globale config — ~/.claude/mcp.json

Van toepassing op alle Claude Code-sessies op je machine:

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

📁 Per-project config — .mcp.json in projectroot

Zelfde indeling als globale config — van toepassing alleen wanneer je in die map werkt:

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

✅ Controleer de verbinding

Na opslaan van de config, openen Claude Code en typ:

/mcp

Je zou **simplestickers** met alle 11 beschikbare tools moeten zien. Als de server niet verbonden is, klik op Opnieuw verbinden.

🖥️

Claude Desktop Instellingen

Belangrijk: Claude Desktop ondersteunt HTTP MCP-transport niet direct — het gebruikt alleen **stdio** transport. Gebruik mcp-remote als proxy. De -y vlag keurt de npm install automatisch goed zonder interactieve prompts.

🍎 macOS

Configbestand: ~/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

Configbestand: %APPDATA%\Claude\claude_desktop_config.json

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

In Windows lanceert Claude Desktop processen zonder shell-context, dus npx moet in cmd /c worden verpakt:

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

Na bewerking van de config, **start Claude Desktop opnieuw op**. Je zou de Simple Stickers-tools in de gereedschapplijst in een gesprek moeten zien.

💡

Snelle Voorbeelden

📡 Volledige REST workflow — vind project → maak taak aan → werk status bij

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

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

# 2. Create a task (use project_id from step 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. Move task to in_progress (use task id from step 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. Mark as done
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<task-uuid>","status":"done"}'

🤖 MCP workflow in Claude Code

Zodra de MCP server is geconfigureerd, kun je natuurlijk met Claude spreken:

Jij: Vind mijn "Website Redesign" project en geef een lijst van alle taken die in_progress zijn

Jij: Maak een taak met hoge prioriteit aan "Fix mobile navigation" met een deadline van 2026-06-30 en voeg notities toe met een checklist

Jij: Verplaats alle taken met de naam "Deploy *" naar done status

Claude gebruikt de MCP-tools automatisch op basis van je natuurlijke taalaanwijzingen.

🔬 Test MCP server rechtstreeks met curl

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

# Handshake (no auth needed)
curl -s -X POST $BASE \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}},"id":1}'

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

# Call a tool
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}'