Documentación de API y MCP de Simple Stickers

🔑

Autenticación

Tanto la API REST como el servidor MCP utilizan autenticación de token Bearer a través de una clave API.

Tipo de token	Duración	Cómo obtenerlo
`ss_<40 caracteres hexadecimales>` — Clave API	De larga duración — válida hasta que sea revocada	Genera en Configuración de Cuenta → pestaña API

🔧 Generando una Clave API

1 Abre Simple Stickers y haz clic en tu avatar en la esquina superior derecha
2 Ve a Configuración de Cuenta → pestaña API
3 Haz clic en Generar Clave API, opcionalmente asígnale un nombre
4
Copia la clave inmediatamente — se muestra solo una vez
La clave comienza con ss_ seguida de 40 caracteres hexadecimales.

📤 Usando el Token

Pasa el token en cada solicitud como un encabezado de Autorización Bearer:

Authorization: Bearer ss_a1b2c3d4e5f6...

Las claves API están vinculadas al usuario que las creó. Todas las operaciones de datos devuelven solo los datos de ese usuario.

📡

API REST

🌐 Endpoint

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

📨 Cuerpo de la Solicitud

Todas las acciones comparten el mismo envoltorio JSON:

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

📬 Respuestas

200 OK Éxito — datos JSON en el cuerpo
4xx / 5xx Error — {"error": "message"}

📁

Proyectos

list_projects

Devuelve todos los proyectos que pertenecen al usuario autenticado.

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

Respuesta: matriz de objetos {"id","name","created_at"}.

find_project

Búsqueda de nombre parcial sin distinción de mayúsculas/minúsculas. Devuelve una matriz de proyectos coincidentes.

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	Requerido
`name`	string	Sí

create_project

Crea un nuevo proyecto. Devuelve el objeto del proyecto creado.

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	Requerido
`name`	string	Sí

rename_project

Renombra un proyecto 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	Requerido
`project_id`	string (UUID)	Sí
`name`	string	Sí

delete_project

Elimina un proyecto y todas sus tareas (cascada). Devuelve {"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. Todas las tareas del proyecto se eliminan permanentemente.

📝

Tareas

list_tasks

Devuelve las tareas en un proyecto, ordenadas por posición. Opcionalmente filtradas por estado.

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 estado:
-d '{"action":"list_tasks","project_id":"<uuid>","status":"in_progress"}'

Parámetro	Tipo	Requerido	Descripción
`project_id`	string (UUID)	Sí
`status`	string	No	Filtrar por valor de estado (ver enumeración abajo)

get_task

Devuelve una única tarea por ID, incluyendo su 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

Crea una nueva tarea en un proyecto. Devuelve el objeto de la tarea creada.

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	Requerido	Por defecto
`project_id`	string (UUID)	Sí
`text`	string	Sí
`status`	string	No	`backlog`
`notes`	string (Markdown)	No	`null`
`priority`	boolean	No	`false`
`color`	string \| null	No	`null` (blanco)
`deadline`	string (YYYY-MM-DD) \| null	No	`null`

update_task

Actualiza uno o más campos de una tarea existente. Se debe proporcionar al menos un campo opcional.

# Mover tarea a 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"}'

# Actualizar múltiples campos a la vez:
-d '{"action":"update_task","task_id":"<uuid>","priority":true,"color":"green","deadline":null}'

Parámetro	Tipo	Requerido
`task_id`	string (UUID)	Sí
`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

delete_task

Elimina permanentemente una tarea. Devuelve {"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 Enumeración

status

backlog
in_progress
review
testing
done

color

yellow
green
blue
null (blanco)

deadline

Cadena YYYY-MM-DD, o null para limpiar.

priority

true = alta prioridad
false = normal

📄

Notas de Tareas (Markdown)

Las notas de tareas se almacenan y transmiten como cadenas Markdown simples. El frontend las renderiza a través de react-markdown. Siempre escriba y lea Markdown — no HTML.

Sintaxis	Resultado
`text`	Negrita
`text`	Cursiva
`~~text~~`	~~Tachado~~
`## Heading`	Encabezado H2
`### Heading`	Encabezado H3
`- item`	Lista con viñetas
`1. item`	Lista numerada
`code`	Código en línea
```\ncode\n```	Bloque de código
`> text`	Cita en bloque
`[text](url)`	Hipervínculo

📋 Ejemplo de nota en 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)"

Notas antiguas: Las notas guardadas antes de la migración de Markdown pueden contener HTML. El frontend las convierte automáticamente en la pantalla. Cuando se lee a través de la API, las notas antiguas pueden devolver cadenas HTML — siempre escriba Markdown, sea tolerante al leer.

⚙️

Configuración

get_column_settings

Devuelve la configuración de visibilidad de columnas Kanban del usuario.

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

Respuesta de ejemplo:

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

columns es null si el usuario no ha personalizado la visibilidad de columnas (se aplican todos los valores por defecto).

❌

Referencia de Errores

Estado HTTP	Valor de `error`	Significado
401	`Unauthorized`	Token faltante o inválido
400	`Missing <param>`	Parámetro requerido no proporcionado
400	`Unknown action`	Nombre de acción no reconocido
403	`Key management requires JWT authentication`	Se intentó gestionar claves con un token de clave API
500	varía	Error inesperado del servidor

🤖

Integración MCP

¿Qué es MCP?

MCP (Model Context Protocol) es un estándar que permite a los clientes de IA (Claude Code, Claude Desktop, Cursor…) conectarse a herramientas externas. A diferencia de la API REST, el servidor MCP se describe a sí mismo — el cliente pregunta qué herramientas existen, luego las llama directamente sin necesidad de conocer URLs o formatos de solicitud.

✅ Usa MCP cuando…

• Quieres que Claude gestione tus tareas conversacionalmente
• Necesitas que la IA descubra las operaciones disponibles por sí sola
• Prefieres una integración plug-and-play con Claude Code / Claude Desktop
• Quieres usar lenguaje natural en lugar de escribir comandos curl

📡 Usa API REST cuando…

• Estás construyendo tus propios scripts de automatización o canalizaciones CI
• Necesitas control granular sobre las solicitudes HTTP
• Estás integrando con sistemas que no soportan MCP
• Quieres procesar respuestas programáticamente

🛠️ Herramientas MCP Disponibles

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 transmisible, JSON-RPC 2.0)

💻

Configuración de Claude Code

Claude Code soporta servidores MCP HTTP de forma nativa — no se necesita proxy. Configura una vez globalmente o por proyecto.

🌐 Configuración global — ~/.claude/mcp.json

Se aplica a todas las sesiones de Claude Code en tu máquina:

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

📁 Configuración por proyecto — .mcp.json en la raíz del proyecto

Mismo formato que la configuración global — se aplica solo cuando trabajas dentro de ese directorio:

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

✅ Verifica la conexión

Después de guardar la configuración, abre Claude Code y escribe:

/mcp

Deberías ver simplestickers listado con las 11 herramientas disponibles. Si el servidor aparece desconectado, haz clic en Reconectar.

🖥️

Configuración de Claude Desktop

Importante: Claude Desktop no soporta transporte MCP HTTP directamente — solo usa transporte stdio. Usa mcp-remote como un proxy. La bandera -y aprueba automáticamente la instalación npm sin indicadores interactivos.

🍎 macOS

Archivo de configuración: ~/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

Archivo de configuración: %APPDATA%\Claude\claude_desktop_config.json

(típicamente C:\Users\<name>\AppData\Roaming\Claude\claude_desktop_config.json)

En Windows, Claude Desktop lanza procesos sin un contexto de shell, por lo que npx debe estar envuelto en 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"
      ]
    }
  }
}

Después de editar la configuración, reinicia Claude Desktop. Deberías ver las herramientas de Simple Stickers aparecer en la lista de herramientas dentro de una conversación.

💡

Ejemplos Rápidos

📡 Flujo de trabajo REST completo — buscar proyecto → crear tarea → actualizar estado

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

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

# 2. Crear una tarea (usar project_id del paso 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 tarea a in_progress (usar task id del paso 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 completado
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_task","task_id":"<task-uuid>","status":"done"}'

🤖 Flujo de trabajo MCP en Claude Code

Una vez configurado el servidor MCP, puedes hablar con Claude naturalmente:

Tú: Encuentra mi proyecto "Website Redesign" y lista todas las tareas que están en in_progress

Tú: Crea una tarea de alta prioridad "Fix mobile navigation" con una fecha de vencimiento del 2026-06-30 y añade notas con una lista de verificación

Tú: Mueve todas las tareas nombradas "Deploy *" al estado completado

Claude utiliza automáticamente las herramientas MCP basadas en tus instrucciones en lenguaje natural.

🔬 Prueba el servidor MCP directamente con curl

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

# Handshake (sin autenticación necesaria)
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 herramientas
curl -s -X POST $BASE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

# Llamar una herramienta
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}'