Simple Stickers API & MCP Documentation

🔑

Authentication

Both the REST API and MCP server use Bearer token authentication via an API key. Claude.ai (web, desktop app, mobile) instead signs in to the MCP server via OAuth — no need to generate or copy a key, see Connect to Claude.ai.

Token type	Lifetime	How to obtain
`ss_<40 hex chars>` — API key	Long-lived — valid until revoked	Generate in Account Settings → API tab
`ss_…` — OAuth-issued key	Long-lived — valid until revoked	Created automatically when you connect Claude.ai (shown in the key list with the source “Connected app”)

🔧 Generating an API Key

1 Open Simple Stickers and click your avatar in the top right
2 Go to Account Settings → API tab
3 Click Generate API Key, optionally give it a name
4
Copy the key immediately — it is shown only once
The key starts with ss_ followed by 40 hex characters.

📤 Using the Token

Pass the token in every request as a Bearer Authorization header:

Authorization: Bearer ss_a1b2c3d4e5f6...

API keys are scoped to the user who created them. All data operations return only that user's data.

📡

REST API

🌐 Endpoint

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

📨 Request Body

All actions share the same JSON envelope:

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

📬 Responses

200 OK Success — JSON data in body
4xx / 5xx Error — {"error": "message"}

📁

Projects

list_projects

Returns all projects belonging to the authenticated user.

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

Response: array of {"id","name","created_at"} objects.

find_project

Case-insensitive partial name search. Returns an array of matching projects.

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	Required
`name`	string	Yes

create_project

Creates a new project. Returns the created project object.

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	Required
`name`	string	Yes

rename_project

Renames an existing 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	Required
`project_id`	string (UUID)	Yes
`name`	string	Yes

delete_project

Deletes a project and all its tasks (cascade). Returns {"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>"}'

⚠️ Irreversible. All tasks in the project are permanently deleted.

📝

Tasks

list_tasks

Returns tasks in a project, ordered by position. Optionally filtered by 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 by status:
-d '{"action":"list_tasks","project_id":"<uuid>","status":"in_progress"}'

# Compact mode without full notes:
-d '{"action":"list_tasks","project_id":"<uuid>","include_notes":false}'

Parameter	Type	Required	Description
`project_id`	string (UUID)	Yes
`status`	string	No	Filter by status value (see enum below)
`include_notes`	boolean	No	Set to `false` to get `notes_preview` (first line) and `notes_chars` instead of full notes — much smaller response, ideal for orchestration loops

get_task

Returns a single task by ID, including its 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

Creates a new task in a project. Returns the created task object.

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	Required	Default
`project_id`	string (UUID)	Yes
`text`	string	Yes
`status`	string	No	`backlog`
`notes`	string (Markdown)	No	`null`
`priority`	boolean	No	`false`
`color`	string \| null	No	`null` (white)
`deadline`	string (YYYY-MM-DD) \| null	No	`null`
`position`	number	No	end of the column (`max + 1000`)

update_task

Updates one or more fields of an existing task. At least one optional field must be provided.

# Move task to 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 multiple fields at once:
-d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'

Parameter	Type	Required
`task_id`	string (UUID)	Yes
`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
`position`	number	No

append_to_notes

Appends text to the end of a task's notes without resending the existing notes. The new text is separated by a blank line (if the notes are empty, only the new text is stored). The operation is atomic, so concurrent appends never overwrite each other. Returns the updated task.

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":"## Test results\n\n- All passed"}'

Parameter	Type	Required
`task_id`	string (UUID)	Yes
`text`	string (Markdown)	Yes

delete_task

Permanently deletes a task. Returns {"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>"}'

📋 Enum Values

status

backlog
in_progress
review
testing
done

color

yellow
green
blue
null (white)

deadline

YYYY-MM-DD string, or null to clear.

priority

true = high priority
false = normal

📄

Task Notes (Markdown)

Task notes are stored and transmitted as plain Markdown strings. The frontend renders them via react-markdown. Always write and read Markdown — not HTML.

Syntax	Result
`text`	Bold
`text`	Italic
`~~text~~`	~~Strikethrough~~
`## Heading`	H2 heading
`### Heading`	H3 heading
`- item`	Bullet list
`1. item`	Numbered list
`code`	Inline code
```\ncode\n```	Code block
`> text`	Blockquote
`[text](url)`	Hyperlink

📋 Example note 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)"

Legacy notes: Notes saved before the Markdown migration may contain HTML. The frontend converts them automatically on display. When reading via the API, old notes may return HTML strings — always write Markdown, be tolerant when reading.

⚙️

Settings

get_column_settings

Returns the user's Kanban column visibility settings.

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

Example response:

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

columns is null if the user has not customised column visibility (all defaults apply).

❌

Error Reference

HTTP status	`error` value	Meaning
401	`Unauthorized`	Missing, invalid or revoked token. The MCP server additionally returns a `WWW-Authenticate` header pointing to the OAuth metadata.
400	`Missing <param>`	Required parameter not provided
400	`Unknown action`	Action name not recognised
403	`Key management requires JWT authentication`	Tried to manage keys with an API key token
500	varies	Unexpected server error

🤖

MCP Integration

What is MCP?

MCP (Model Context Protocol) is a standard that lets AI clients (Claude Code, Claude Desktop, Cursor…) connect to external tools. Unlike the REST API, the MCP server describes itself — the client asks which tools exist, then calls them directly without needing to know URLs or request formats.

✅ Use MCP when…

• You want Claude to manage your tasks conversationally
• You need the AI to discover available operations on its own
• You prefer a plug-and-play integration with Claude Code / Claude Desktop
• You want to use natural language instead of writing curl commands

📡 Use REST API when…

• You are building your own automation scripts or CI pipelines
• You need fine-grained control over HTTP requests
• You are integrating with systems that don't support MCP
• You want to process responses programmatically

🛠️ Available 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 endpoint: https://www.simplestickers.app/api/mcp (Streamable HTTP transport, JSON-RPC 2.0)

🔌 How to connect

• Claude.ai — web, desktop app, mobile: custom connector with OAuth sign-in, no API key — guide
• Claude Code: config with an API key in the header, or OAuth sign-in — guide
• n8n and other tools: HTTP MCP client with the header Authorization: Bearer ss_… (key from Account Settings → API)

☁️

Connect to Claude.ai

Add Simple Stickers as a custom connector in Claude. You sign in with your Simple Stickers account and allow access — no API key to generate or paste anywhere. The connector then works in Claude on the web, in the desktop app and on mobile.

🔗 Steps

1 In Claude, open Settings → Connectors and click Add custom connector
2
Enter any name (e.g. Simple Stickers) and the server URL:
https://www.simplestickers.app/api/mcp
3 Click Connect — a Simple Stickers page opens
4 Sign in (with email or Google) and click Allow. You are taken back to Claude and the connector is connected.

✅ What next

• The connector syncs to the Claude desktop app and to mobile — you set it up only once
• In a conversation just write something like “What tasks do I have in the Website project?”
• Claude has the same access as you: it can view, create, edit and delete your projects and tasks

🔌 Disconnecting

• In Simple Stickers, open Account Settings → API tab
• Revoke the key with the source Connected app (named “Claude”) using the Revoke button
• From then on Claude has no access to your account; to reconnect, just click Connect in Claude again

On Claude Team / Enterprise plans only the organization owner can add custom connectors; other members then just connect with their own account.

💻

Claude Code Setup

Claude Code supports HTTP MCP servers natively — no proxy needed. Configure once globally or per project.

🔐 Easiest: OAuth sign-in (no API key)

Add the server without a header, then sign in with /mcp → simplestickers → Authenticate. A browser opens with the same consent page as for Claude.ai.

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

For scripts and shared configs you can still use an API key in the header — see below.

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

Applies to all Claude Code sessions on your 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 project root

Same format as global config — applies only when working inside that directory:

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

✅ Verify the connection

After saving the config, open Claude Code and type:

/mcp

You should see simplestickers listed with all 12 available tools. If the server shows as disconnected, click Reconnect.

🖥️

Claude Desktop Setup

Recommended: the easiest way is to add Simple Stickers as a connector in Claude.ai — it automatically shows up in Claude Desktop and on mobile too, with no config files and no API key. See Connect to Claude.ai. The manual configuration below is an alternative for a local setup with an API key.

Important: Claude Desktop does not support HTTP MCP transport directly — it uses stdio transport only. Use mcp-remote as a proxy. The -y flag auto-approves the npm install without interactive prompts.

🍎 macOS

Config file: ~/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

Config file: %APPDATA%\Claude\claude_desktop_config.json

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

On Windows, Claude Desktop launches processes without a shell context, so npx must be wrapped 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"
      ]
    }
  }
}

After editing the config, restart Claude Desktop. You should see the Simple Stickers tools appear in the tool list inside a conversation.

💡

Quick Examples

📡 Complete REST workflow — find project → create task → update status

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

Once the MCP server is configured, you can talk to Claude naturally:

You: Find my "Website Redesign" project and list all tasks that are in_progress

You: Create a high-priority task "Fix mobile navigation" with a deadline of 2026-06-30 and add notes with a checklist

You: Move all tasks named "Deploy *" to done status

Claude uses the MCP tools automatically based on your natural language instructions.

🔬 Test MCP server directly with 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}'