Documentação da API e MCP do Simple Stickers

🔑

Autenticação

Tanto a API REST quanto o servidor MCP usam autenticação por token Bearer via uma chave de API.

Tipo de token	Duração	Como obter
`ss_<40 hex chars>` — Chave de API	Longa duração — válida até ser revogada	Gerar em Configurações da Conta → Aba API

🔧 Gerando uma Chave de API

1 Abra Simple Stickers e clique no seu avatar no canto superior direito
2 Vá para Configurações da Conta → Aba API
3 Clique em Gerar Chave de API, opcionalmente dê um nome a ela
4
Copie a chave imediatamente — ela é mostrada apenas uma vez
A chave começa com ss_ seguida de 40 caracteres hexadecimais.

📤 Usando o Token

Passe o token em cada requisição como cabeçalho Authorization Bearer:

Authorization: Bearer ss_a1b2c3d4e5f6...

As chaves de API estão vinculadas ao usuário que as criou. Todas as operações de dados retornam apenas os dados desse usuário.

📡

API REST

🌐 Endpoint

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

📨 Corpo da Requisição

Todas as ações compartilham o mesmo envelope JSON:

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

📬 Respostas

200 OK Sucesso — dados JSON no corpo
4xx / 5xx Erro — {"error": "message"}

📁

Projetos

list_projects

Retorna todos os projetos do usuário autenticado.

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

Resposta: array de objetos {"id","name","created_at"}.

find_project

Busca por nome parcial, insensível a maiúsculas e minúsculas. Retorna um array de projetos correspondentes.

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

Parâmetro	Tipo	Obrigatório
`name`	string	Sim

create_project

Cria um novo projeto. Retorna o objeto do projeto criado.

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

Parâmetro	Tipo	Obrigatório
`name`	string	Sim

rename_project

Renomeia um projeto existente.

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

Parâmetro	Tipo	Obrigatório
`project_id`	string (UUID)	Sim
`name`	string	Sim

delete_project

Deleta um projeto e todas as suas tarefas (cascata). Retorna {"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>"}'

⚠️ Irreversível. Todas as tarefas no projeto são permanentemente deletadas.

📝

Tarefas

list_tasks

Retorna tarefas em um projeto, ordenadas por posição. Opcionalmente filtradas por 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>"}'

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

Parâmetro	Tipo	Obrigatório	Descrição
`project_id`	string (UUID)	Sim
`status`	string	Não	Filtrar pelo valor de status (veja enum abaixo)

get_task

Retorna uma única tarefa pelo ID, incluindo seu 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

Cria uma nova tarefa em um projeto. Retorna o objeto da tarefa criada.

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

Parâmetro	Tipo	Obrigatório	Padrão
`project_id`	string (UUID)	Sim
`text`	string	Sim
`status`	string	Não	`backlog`
`notes`	string (Markdown)	Não	`null`
`priority`	boolean	Não	`false`
`color`	string \| null	Não	`null` (white)
`deadline`	string (YYYY-MM-DD) \| null	Não	`null`

update_task

Atualiza um ou mais campos de uma tarefa existente. Pelo menos um campo opcional deve ser fornecido.

# Mover tarefa para 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"}'

# Atualizar múltiplos campos de uma vez:
-d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'

Parâmetro	Tipo	Obrigatório
`task_id`	string (UUID)	Sim
`text`	string	Não
`status`	string	Não
`notes`	string (Markdown) \| null	Não
`priority`	boolean	Não
`color`	string \| null	Não
`deadline`	string (YYYY-MM-DD) \| null	Não

delete_task

Deleta permanentemente uma tarefa. Retorna {"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>"}'

📋 Valores de Enum

status

backlog
in_progress
review
testing
done

color

yellow
green
blue
null (white)

deadline

string YYYY-MM-DD, ou null para limpar.

priority

true = alta prioridade
false = normal

📄

Anotações de Tarefa (Markdown)

Anotações de tarefa são armazenadas e transmitidas como strings Markdown simples. O frontend as renderiza via react-markdown. Sempre escreva e leia Markdown — não HTML.

Sintaxe	Resultado
`text`	Negrito
`text`	Itálico
`~~text~~`	~~Riscado~~
`## Heading`	Cabeçalho H2
`### Heading`	Cabeçalho H3
`- item`	Lista com marcadores
`1. item`	Lista numerada
`code`	Código inline
```\ncode\n```	Bloco de código
`> text`	Citação
`[text](url)`	Hyperlink

📋 Exemplo de anotação em 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)"

Anotações legadas: Anotações salvas antes da migração para Markdown podem conter HTML. O frontend as converte automaticamente ao exibir. Ao ler pela API, anotações antigas podem retornar strings HTML — sempre escreva Markdown, seja tolerante ao ler.

⚙️

Configurações

get_column_settings

Retorna as configurações de visibilidade de coluna Kanban do usuário.

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

Exemplo de resposta:

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

columns é null se o usuário não personalizou a visibilidade das colunas (todos os padrões se aplicam).

❌

Referência de Erros

Status HTTP	valor de `error`	Significado
401	`Unauthorized`	Token ausente ou inválido
400	`Missing <param>`	Parâmetro obrigatório não fornecido
400	`Unknown action`	Nome de ação não reconhecido
403	`Key management requires JWT authentication`	Tentou gerenciar chaves com um token de chave de API
500	varia	Erro inesperado do servidor

🤖

Integração MCP

O que é MCP?

MCP (Model Context Protocol) é um padrão que permite que clientes de IA (Claude Code, Claude Desktop, Cursor…) se conectem a ferramentas externas. Diferentemente da API REST, o servidor MCP se descreve a si mesmo — o cliente pergunta quais ferramentas existem, depois as chama diretamente sem precisar saber URLs ou formatos de requisição.

✅ Use MCP quando…

• Você quer que Claude gerencie suas tarefas conversacionalmente
• Você precisa que a IA descubra as operações disponíveis por conta própria
• Você prefere uma integração pronta com Claude Code / Claude Desktop
• Você quer usar linguagem natural em vez de escrever comandos curl

📡 Use API REST quando…

• Você está construindo seus próprios scripts de automação ou pipelines CI
• Você precisa de controle granular sobre requisições HTTP
• Você está integrando com sistemas que não suportam MCP
• Você quer processar respostas programaticamente

🛠️ Ferramentas MCP Disponíveis

list_projects

find_project

create_project

rename_project

delete_project

get_column_settings

list_tasks

get_task

create_task

update_task

delete_task

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

💻

Configuração do Claude Code

Claude Code suporta servidores MCP HTTP nativamente — não é necessário proxy. Configure uma vez globalmente ou por projeto.

🌐 Configuração global — ~/.claude/mcp.json

Se aplica a todas as sessões de Claude Code na sua máquina:

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

📁 Configuração por projeto — .mcp.json na raiz do projeto

Mesmo formato que a configuração global — se aplica apenas quando trabalhando dentro desse diretório:

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

✅ Verificar a conexão

Depois de salvar a configuração, abra Claude Code e digite:

/mcp

Você deve ver simplestickers listado com todas as 11 ferramentas disponíveis. Se o servidor aparecer como desconectado, clique em Reconectar.

🖥️

Configuração do Claude Desktop

Importante: Claude Desktop não suporta transporte MCP HTTP diretamente — usa apenas transporte stdio. Use mcp-remote como proxy. A flag -y aprova automaticamente a instalação npm sem prompts interativos.

🍎 macOS

Arquivo de configuração: ~/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

Arquivo de configuração: %APPDATA%\Claude\claude_desktop_config.json

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

No Windows, Claude Desktop inicia processos sem contexto de shell, então npx deve ser envolvido em 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"
      ]
    }
  }
}

Depois de editar a configuração, reinicie Claude Desktop. Você deve ver as ferramentas Simple Stickers aparecer na lista de ferramentas dentro de uma conversa.

💡

Exemplos Rápidos

📡 Fluxo REST completo — encontrar projeto → criar tarefa → atualizar status

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

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

# 2. Criar uma tarefa (use project_id da etapa 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. Mover tarefa para in_progress (use task id da etapa 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. Marcar como concluído
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<task-uuid>","status":"done"}'

🤖 Fluxo MCP em Claude Code

Depois que o servidor MCP está configurado, você pode conversar com Claude naturalmente:

Você: Encontre meu projeto "Website Redesign" e liste todas as tarefas que estão in_progress

Você: Crie uma tarefa de alta prioridade "Fix mobile navigation" com prazo de 2026-06-30 e adicione anotações com uma checklist

Você: Mova todas as tarefas nomeadas "Deploy *" para status concluído

Claude usa as ferramentas MCP automaticamente com base em suas instruções em linguagem natural.

🔬 Testar servidor MCP diretamente com curl

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

# Handshake (sem autenticação necessária)
curl -s -X POST $BASE \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}},"id":1}'

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

# Chamar uma ferramenta
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}'