Dokumentacja Simple Stickers API & MCP

🔑

Uwierzytelnianie

Zarówno REST API, jak i serwer MCP używają uwierzytelniania tokenu Bearer za pośrednictwem klucza API. Claude.ai (web, aplikacja desktopowa, urządzenia mobilne) loguje się do serwera MCP zamiast tego przez OAuth — nie musisz generować ani kopiować klucza, zobacz Połączenie z Claude.ai.

Typ tokenu	Okres ważności	Jak uzyskać
`ss_<40 hex chars>` — klucz API	Długotrwały — ważny aż do odwołania	Wygeneruj w Ustawieniach konta → Zakładka API
`ss_…` — klucz wydany przez OAuth	Długotrwały — ważny aż do odwołania	Tworzony automatycznie przy połączeniu Claude.ai (na liście kluczy ze źródłem „Połączona aplikacja”)

🔧 Generowanie klucza API

1 Otwórz Simple Stickers i kliknij swoją awatarkę w prawym górnym rogu
2 Przejdź do Ustawień konta → Zakładka API
3 Kliknij Wygeneruj klucz API, opcjonalnie nadaj mu nazwę
4
Skopiuj klucz natychmiast — jest wyświetlany tylko raz
Klucz zaczyna się od ss_ i zawiera 40 znaków szesnastkowych.

📤 Używanie tokenu

Przekaż token w każdym żądaniu jako nagłówek autoryzacji Bearer:

Authorization: Bearer ss_a1b2c3d4e5f6...

Klucze API są ograniczone do użytkownika, który je utworzył. Wszystkie operacje na danych zwracają tylko dane tego użytkownika.

📡

REST API

🌐 Punkt końcowy

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

📨 Treść żądania

Wszystkie akcje używają tej samej koperty JSON:

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

📬 Odpowiedzi

200 OK Sukces — dane JSON w treści
4xx / 5xx Błąd — {"error": "message"}

📁

Projekty

list_projects

Zwraca wszystkie projekty należące do uwierzytelnionego użytkownika.

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

Odpowiedź: tablica obiektów {"id","name","created_at"}.

find_project

Wyszukiwanie częściowego nazwy projektu bez uwzględniania wielkości liter. Zwraca tablicę pasujących projektów.

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

Parametr	Typ	Wymagane
`name`	string	Tak

create_project

Tworzy nowy projekt. Zwraca stworzony obiekt projektu.

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

Parametr	Typ	Wymagane
`name`	string	Tak

rename_project

Zmienia nazwę istniejącego projektu.

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

Parametr	Typ	Wymagane
`project_id`	string (UUID)	Tak
`name`	string	Tak

delete_project

Usuwa projekt i wszystkie jego zadania (kaskadowo). Zwraca {"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>"}'

⚠️ Nieodwracalne. Wszystkie zadania w projekcie są na stałe usuwane.

📝

Zadania

list_tasks

Zwraca zadania w projekcie, uporządkowane według pozycji. Opcjonalnie filtrowane po statusie.

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

# Filtrowanie po statusie:
-d '{"action":"list_tasks","project_id":"<uuid>","status":"in_progress"}'

# Tryb kompaktowy bez pełnych notatek:
-d '{"action":"list_tasks","project_id":"<uuid>","include_notes":false}'

Parametr	Typ	Wymagane	Opis
`project_id`	string (UUID)	Tak
`status`	string	Nie	Filtruj po wartości statusu (zobacz wyliczenie poniżej)
`include_notes`	boolean	Nie	Przy `false` zwraca `notes_preview` (pierwszy wiersz) i `notes_chars` zamiast pełnych notatek — znacznie mniejsza odpowiedź, idealna do pętli orkiestracyjnych

get_task

Zwraca pojedyncze zadanie po ID, łącznie z 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

Tworzy nowe zadanie w projekcie. Zwraca stworzony obiekt zadania.

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

Parametr	Typ	Wymagane	Domyślnie
`project_id`	string (UUID)	Tak
`text`	string	Tak
`status`	string	Nie	`backlog`
`notes`	string (Markdown)	Nie	`null`
`priority`	boolean	Nie	`false`
`color`	string \| null	Nie	`null` (białe)
`deadline`	string (YYYY-MM-DD) \| null	Nie	`null`
`position`	number	Nie	koniec kolumny (`max + 1000`)

update_task

Aktualizuje jedno lub więcej pól istniejącego zadania. Wymagane jest co najmniej jedno pole opcjonalne.

# Przenieś zadanie do 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"}'

# Aktualizuj wiele pól jednocześnie:
-d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'

Parametr	Typ	Wymagane
`task_id`	string (UUID)	Tak
`text`	string	Nie
`status`	string	Nie
`notes`	string (Markdown) \| null	Nie
`priority`	boolean	Nie
`color`	string \| null	Nie
`deadline`	string (YYYY-MM-DD) \| null	Nie
`position`	number	Nie

append_to_notes

Dopisuje tekst na koniec notatek zadania bez ponownego wysyłania istniejących notatek. Nowy tekst jest oddzielony pustą linią (jeśli notatki są puste, zapisywany jest tylko nowy tekst). Operacja jest atomowa, więc równoczesne dopisania nie nadpisują się nawzajem. Zwraca zaktualizowane zadanie.

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":"## Wyniki testów\n\n- Wszystko przeszło"}'

Parametr	Typ	Wymagane
`task_id`	string (UUID)	Tak
`text`	string (Markdown)	Tak

delete_task

Trwale usuwa zadanie. Zwraca {"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>"}'

📋 Wartości wyliczenia

status

backlog
in_progress
review
testing
done

color

yellow
green
blue
null (białe)

deadline

YYYY-MM-DD string, lub null aby wyczyścić.

priority

true = wysoki priorytet
false = normalny

📄

Notatki zadań (Markdown)

Notatki zadań są przechowywane i transmitowane jako zwykłe ciągi Markdown. Frontend je renderuje za pośrednictwem react-markdown. Zawsze pisz i czytaj Markdown — nie HTML.

Składnia	Wynik
`text`	Pogrubienie
`text`	Kursywa
`~~text~~`	~~Przekreślenie~~
`## Heading`	Nagłówek H2
`### Heading`	Nagłówek H3
`- item`	Lista wypunktowana
`1. item`	Lista numerowana
`code`	Kod wbudowany
```\ncode\n```	Blok kodu
`> text`	Cytat blokowy
`[text](url)`	Hiperłącze

📋 Przykładowa notatka w 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)"

Notatki z przeszłości: Notatki zapisane przed migracją Markdown mogą zawierać HTML. Frontend automatycznie je konwertuje na wyświetlaniu. Podczas czytania przez API, stare notatki mogą zwrócić ciągi HTML — zawsze pisz Markdown, bądź tolerancyjny podczas czytania.

⚙️

Ustawienia

get_column_settings

Zwraca ustawienia widoczności kolumn Kanban użytkownika.

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

Przykładowa odpowiedź:

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

columns to null jeśli użytkownik nie dostosował widoczności kolumn (obowiązują wszystkie domyślne).

❌

Dokumentacja błędów

Status HTTP	Wartość `error`	Znaczenie
401	`Unauthorized`	Brakujący, nieprawidłowy lub unieważniony token. Serwer MCP dodatkowo zwraca nagłówek `WWW-Authenticate` z odnośnikiem do metadanych OAuth.
400	`Missing <param>`	Wymagany parametr nie został podany
400	`Unknown action`	Nazwa akcji nie została rozpoznana
403	`Key management requires JWT authentication`	Próba zarządzania kluczami za pomocą tokenu klucza API
500	zmienia się	Nieoczekiwany błąd serwera

🤖

Integracja MCP

Co to jest MCP?

MCP (Model Context Protocol) to standard, który pozwala klientom AI (Claude Code, Claude Desktop, Cursor…) łączyć się z zewnętrznymi narzędziami. W przeciwieństwie do REST API, serwer MCP się opisuje — klient pyta, które narzędzia istnieją, a następnie je bezpośrednio wywołuje bez konieczności znania adresów URL lub formatów żądań.

✅ Używaj MCP gdy…

• Chcesz, aby Claude zarządzał Twoimi zadaniami konwersacyjnie
• Potrzebujesz, aby AI samodzielnie odkrywała dostępne operacje
• Preferujesz integrację plug-and-play z Claude Code / Claude Desktop
• Chcesz używać języka naturalnego zamiast pisać komendy curl

📡 Używaj REST API gdy…

• Budujesz własne skrypty automatyzacji lub potoki CI
• Potrzebujesz precyzyjnej kontroli nad żądaniami HTTP
• Integrujesz się z systemami, które nie obsługują MCP
• Chcesz przetwarzać odpowiedzi programowo

🛠️ Dostępne narzędzia MCP

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

Punkt końcowy MCP: https://www.simplestickers.app/api/mcp (Transport HTTP przesyłowy, JSON-RPC 2.0)

🔌 Jak się połączyć

• Claude.ai — web, aplikacja desktopowa, urządzenia mobilne: własny konektor z logowaniem przez OAuth, bez klucza API — instrukcja
• Claude Code: konfiguracja z kluczem API w nagłówku lub logowanie przez OAuth — instrukcja
• n8n i inne narzędzia: klient HTTP MCP z nagłówkiem Authorization: Bearer ss_… (klucz z Ustawień konta → API)

☁️

Połączenie z Claude.ai

Dodaj Simple Stickers jako własny konektor w Claude. Zalogujesz się swoim kontem Simple Stickers i zezwolisz na dostęp — nie musisz generować ani nigdzie wklejać klucza API. Konektor działa następnie w Claude w przeglądarce, w aplikacji desktopowej i na urządzeniach mobilnych.

🔗 Kroki

1 W Claude otwórz Settings → Connectors i kliknij Add custom connector
2
Wpisz dowolną nazwę (np. Simple Stickers) i adres URL serwera:
https://www.simplestickers.app/api/mcp
3 Kliknij Connect — otworzy się strona Simple Stickers
4 Zaloguj się (e-mailem lub przez Google) i kliknij Zezwól. Wrócisz do Claude, a konektor będzie połączony.

✅ Co dalej

• Konektor synchronizuje się z aplikacją desktopową Claude i z urządzeniami mobilnymi — konfigurujesz go tylko raz
• W rozmowie wystarczy napisać np. „Jakie mam zadania w projekcie Web?”
• Claude ma taki sam dostęp jak Ty: widzi, tworzy, edytuje i usuwa Twoje projekty i zadania

🔌 Odłączenie

• W Simple Stickers otwórz Ustawienia konta → Zakładka API
• Klucz ze źródłem Połączona aplikacja (nazwa „Claude”) unieważnij przyciskiem Unieważnij
• Od tej chwili Claude nie ma dostępu do Twojego konta; aby połączyć się ponownie, wystarczy w Claude znowu kliknąć Connect

W planach Team / Enterprise Claude własne konektory może dodawać tylko właściciel organizacji; pozostali członkowie jedynie łączą się swoim kontem.

💻

Konfiguracja Claude Code

Claude Code natywnie obsługuje serwery MCP HTTP — nie potrzebny jest żaden proxy. Skonfiguruj raz globalnie lub dla każdego projektu.

🔐 Najprościej: logowanie przez OAuth (bez klucza API)

Dodaj serwer bez nagłówka, a następnie zaloguj się poleceniem /mcp → simplestickers → Authenticate. Otworzy się przeglądarka z tą samą stroną zgody co w Claude.ai.

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

W skryptach i współdzielonych konfiguracjach możesz nadal używać klucza API w nagłówku — zobacz poniżej.

🌐 Konfiguracja globalna — ~/.claude/mcp.json

Dotyczy wszystkich sesji Claude Code na Twojej maszynie:

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

📁 Konfiguracja dla projektu — .mcp.json w katalogu głównym

Ten sam format co konfiguracja globalna — dotyczy tylko pracy w tym katalogu:

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

✅ Weryfikacja połączenia

Po zapisaniu konfiguracji otwórz Claude Code i wpisz:

/mcp

Powinieneś zobaczyć simplestickers na liście z wszystkimi 12 dostępnymi narzędziami. Jeśli serwer jest wyświetlany jako rozłączony, kliknij Reconnect.

🖥️

Konfiguracja Claude Desktop

Zalecane: najprościej jest dodać Simple Stickers jako konektor w Claude.ai — automatycznie pojawi się też w Claude Desktop i na urządzeniach mobilnych, bez plików konfiguracyjnych i klucza API. Zobacz Połączenie z Claude.ai. Ręczna konfiguracja poniżej to alternatywa dla lokalnej konfiguracji z kluczem API.

Ważne: Claude Desktop nie obsługuje bezpośrednio transportu MCP HTTP — używa tylko transportu stdio. Używaj mcp-remote jako proxy. Flaga -y automatycznie zatwierdza instalację npm bez interaktywnych monitów.

🍎 macOS

Plik konfiguracyjny: ~/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

Plik konfiguracyjny: %APPDATA%\Claude\claude_desktop_config.json

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

Na Windows, Claude Desktop uruchamia procesy bez kontekstu powłoki, dlatego npx musi być opakowany w 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"
      ]
    }
  }
}

Po edytowaniu konfiguracji zrestartuj Claude Desktop. Powinieneś zobaczyć narzędzia Simple Stickers w liście narzędzi wewnątrz rozmowy.

💡

Szybkie przykłady

📡 Kompletny przepływ REST — znajdź projekt → utwórz zadanie → zaktualizuj status

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

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

# 2. Utwórz zadanie (użyj project_id z kroku 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. Przenieś zadanie do in_progress (użyj task id z kroku 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. Oznacz jako gotowe
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<task-uuid>","status":"done"}'

🤖 Przepływ MCP w Claude Code

Gdy serwer MCP jest skonfigurowany, możesz rozmawiać z Claude naturalnie:

Ty: Znajdź mój projekt "Website Redesign" i wyświetl wszystkie zadania, które są w_progress

Ty: Utwórz zadanie o wysokim priorytecie "Fix mobile navigation" z terminem 2026-06-30 i dodaj notatki z listą kontrolną

Ty: Przenieś wszystkie zadania nazwane "Deploy *" do statusu gotowe

Claude automatycznie używa narzędzi MCP na podstawie Twoich instrukcji w języku naturalnym.

🔬 Testuj serwer MCP bezpośrednio za pomocą 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}'

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

# Wywołaj narzędzie
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}'