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. Claude.ai (web, aplicación de escritorio, móvil) se conecta al servidor MCP mediante OAuth — no necesitas generar ni copiar ninguna clave, consulta Conectar con Claude.ai.

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
`ss_…` — clave emitida mediante OAuth	De larga duración — válida hasta que sea revocada	Se crea automáticamente al conectar Claude.ai (aparece en la lista de claves con el origen «App conectada»)

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

# Modo compacto sin notas completas:
-d '{"action":"list_tasks","project_id":"<uuid>","include_notes":false}'

Parámetro	Tipo	Requerido	Descripción
`project_id`	string (UUID)	Sí
`status`	string	No	Filtrar por valor de estado (ver enumeración abajo)
`include_notes`	boolean	No	Con `false` se devuelven `notes_preview` (primera línea) y `notes_chars` en lugar de las notas completas — respuesta mucho más pequeña, ideal para bucles de orquestación

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`
`position`	number	No	final de la columna (`max + 1000`)

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

append_to_notes

Añade texto al final de las notas de una tarea sin reenviar las notas existentes. El nuevo texto se separa con una línea en blanco (si las notas están vacías, solo se guarda el nuevo texto). La operación es atómica, por lo que las adiciones simultáneas no se sobrescriben. Devuelve la tarea actualizada.

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":"## Resultado de las pruebas\n\n- Todo correcto"}'

Parámetro	Tipo	Requerido
`task_id`	string (UUID)	Sí
`text`	string (Markdown)	Sí

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, inválido o revocado. Además, el servidor MCP devuelve el encabezado `WWW-Authenticate` con un enlace a los metadatos OAuth.
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

append_to_notes

delete_task

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

🔌 Cómo conectarse

• Claude.ai — web, aplicación de escritorio, móvil: conector personalizado con inicio de sesión OAuth, sin clave API — guía
• Claude Code: configuración con la clave API en un encabezado, o inicio de sesión mediante OAuth — guía
• n8n y otras herramientas: cliente MCP HTTP con el encabezado Authorization: Bearer ss_… (clave de Configuración de Cuenta → API)

☁️

Conectar con Claude.ai

Añade Simple Stickers como conector personalizado en Claude. Inicias sesión con tu cuenta de Simple Stickers y autorizas el acceso — no necesitas generar ni pegar ninguna clave API. El conector funciona después en Claude en la web, en la aplicación de escritorio y en el móvil.

🔗 Pasos

1 En Claude, abre Settings → Connectors y haz clic en Add custom connector
2
Introduce cualquier nombre (p. ej. Simple Stickers) y la URL del servidor:
https://www.simplestickers.app/api/mcp
3 Haz clic en Connect — se abrirá una página de Simple Stickers
4 Inicia sesión (con correo electrónico o Google) y haz clic en Permitir. Volverás a Claude y el conector quedará conectado.

✅ Y después

• El conector se sincroniza con la aplicación de escritorio de Claude y con el móvil — solo lo configuras una vez
• En la conversación basta con escribir, por ejemplo, «¿Qué tareas tengo en el proyecto Web?»
• Claude tiene el mismo acceso que tú: ve, crea, edita y elimina tus proyectos y tareas

🔌 Desconectar

• En Simple Stickers, abre Configuración de Cuenta → pestaña API
• Revoca la clave con el origen App conectada (nombre «Claude») con el botón Revocar
• A partir de ese momento Claude ya no tiene acceso a tu cuenta; para volver a conectarlo, basta con hacer clic de nuevo en Connect en Claude

En los planes Team / Enterprise de Claude, solo el propietario de la organización puede añadir conectores personalizados; los demás miembros solo se conectan con su propia cuenta.

💻

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.

🔐 Lo más sencillo: inicio de sesión mediante OAuth (sin clave API)

Añade el servidor sin encabezado y luego inicia sesión con /mcp → simplestickers → Authenticate. Se abrirá el navegador con la misma página de consentimiento que en Claude.ai.

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

Para scripts y configuraciones compartidas puedes seguir usando la clave API en un encabezado — consulta más abajo.

🌐 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 12 herramientas disponibles. Si el servidor aparece desconectado, haz clic en Reconectar.

🖥️

Configuración de Claude Desktop

Recomendado: lo más sencillo es añadir Simple Stickers como conector en Claude.ai — aparecerá automáticamente también en Claude Desktop y en el móvil, sin archivos de configuración ni clave API. Consulta Conectar con Claude.ai. La configuración manual de abajo es una alternativa para una instalación local con clave API.

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"

# Sin token → HTTP 401 + WWW-Authenticate (descubrimiento OAuth)
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}'

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