Simple Stickers API & MCP Documentatie

🔑

Authenticatie

Zowel de REST API als MCP server gebruiken Bearer token authenticatie via een API-sleutel. Claude.ai (web, desktop-app, mobiel) meldt zich bij de MCP-server in plaats daarvan aan via OAuth — je hoeft geen sleutel te genereren of te kopiëren, zie Verbinden met Claude.ai.

Tokentype	Levensduur	Hoe verkrijgen
`ss_<40 hex chars>` — API-sleutel	Langdurig — geldig tot ingetrokken	Genereer in Accountinstellingen → API-tabblad
`ss_…` — via OAuth uitgegeven sleutel	Langdurig — geldig tot ingetrokken	Wordt automatisch aangemaakt bij het verbinden van Claude.ai (in de sleutellijst met bron „Gekoppelde app”)

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

# Compacte modus zonder volledige notities:
-d '{"action":"list_tasks","project_id":"<uuid>","include_notes":false}'

Parameter	Type	Vereist	Beschrijving
`project_id`	string (UUID)	Ja
`status`	string	Nee	Filter op statuswaarde (zie enum hieronder)
`include_notes`	boolean	Nee	Bij `false` worden `notes_preview` (eerste regel) en `notes_chars` teruggegeven in plaats van de volledige notities — veel kleinere respons, ideaal voor orkestratie-loops

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`
`position`	number	Nee	einde van de kolom (`max + 1000`)

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
`position`	number	Nee

append_to_notes

Voegt tekst toe aan het einde van de notities van een taak zonder de bestaande notities opnieuw te versturen. De nieuwe tekst wordt gescheiden door een lege regel (als de notities leeg zijn, wordt alleen de nieuwe tekst opgeslagen). De bewerking is atomair, dus gelijktijdige toevoegingen overschrijven elkaar niet. Geeft de bijgewerkte taak terug.

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":"## Testresultaten\n\n- Alles geslaagd"}'

Parameter	Type	Vereist
`task_id`	string (UUID)	Ja
`text`	string (Markdown)	Ja

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, is ongeldig of ingetrokken. De MCP-server geeft daarnaast een `WWW-Authenticate`-header terug met een verwijzing naar de OAuth-metadata.
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

append_to_notes

delete_task

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

🔌 Hoe verbinden

• Claude.ai — web, desktop-app, mobiel: aangepaste connector met aanmelding via OAuth, zonder API-sleutel — handleiding
• Claude Code: configuratie met API-sleutel in de header, of aanmelding via OAuth — handleiding
• n8n en andere tools: HTTP MCP-client met de header Authorization: Bearer ss_… (sleutel uit Accountinstellingen → API-tabblad)

☁️

Verbinden met Claude.ai

Voeg Simple Stickers toe als aangepaste connector in Claude. Je meldt je aan met je Simple Stickers-account en geeft toegang — je hoeft geen API-sleutel te genereren of ergens te plakken. De connector werkt daarna in Claude op het web, in de desktop-app en op mobiel.

🔗 Stappen

1 Open in Claude Settings → Connectors en klik op Add custom connector
2
Voer een willekeurige naam in (bijv. Simple Stickers) en de server-URL:
https://www.simplestickers.app/api/mcp
3 Klik op Connect — de Simple Stickers-pagina wordt geopend
4 Meld je aan (met e-mail of via Google) en klik op Toestaan. Je keert terug naar Claude en de connector is verbonden.

✅ Wat nu

• De connector wordt gesynchroniseerd naar de Claude desktop-app en naar mobiel — je stelt hem maar één keer in
• In een gesprek typ je bijvoorbeeld gewoon „Welke taken heb ik in het project Web?”
• Claude heeft dezelfde toegang als jij: bekijkt, maakt, bewerkt en verwijdert je projecten en taken

🔌 Verbinding verbreken

• Open in Simple Stickers Accountinstellingen → API tabblad
• Trek de sleutel met bron Gekoppelde app (naam „Claude”) in met de knop Intrekken
• Vanaf dat moment heeft Claude geen toegang meer tot je account; om opnieuw te verbinden klik je in Claude gewoon weer op Connect

Bij Team / Enterprise-abonnementen van Claude kan alleen de eigenaar van de organisatie aangepaste connectors toevoegen; de andere leden verbinden zich daarna gewoon met hun eigen account.

💻

Claude Code Instellingen

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

🔐 Het eenvoudigst: aanmelden via OAuth (zonder API-sleutel)

Voeg de server toe zonder header en meld je daarna aan met het commando /mcp → simplestickers → Authenticate. Er opent een browser met dezelfde toestemmingspagina als bij Claude.ai.

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

Voor scripts en gedeelde configuraties kun je nog steeds een API-sleutel in de header gebruiken — zie hieronder.

🌐 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 12 beschikbare tools moeten zien. Als de server niet verbonden is, klik op Opnieuw verbinden.

🖥️

Claude Desktop Instellingen

Aanbevolen: het eenvoudigst is Simple Stickers als connector toe te voegen in Claude.ai — hij verschijnt dan automatisch ook in Claude Desktop en op mobiel, zonder configuratiebestanden en API-sleutel. Zie Verbinden met Claude.ai. De handmatige configuratie hieronder is een alternatief voor een lokale installatie met API-sleutel.

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"

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

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