API y servidor MCP
Scrumbo tiene una API REST JSON y un servidor Model Context Protocol (MCP), para que tú (o un asistente de IA como Claude) puedas leer y gestionar boards e historias desde fuera de la aplicación web.
Autenticación
Cada solicitud necesita una clave API personal. Crea una en tu página de cuenta — se muestra una sola vez, así que cópiala de inmediato.
Envíala como token bearer en cada solicitud:
Authorization: Bearer sbo_your_key_hereAPI REST
La API está disponible en https://scrumbo.com/api/v1 y devuelve JSON. Una clave tiene exactamente tu acceso: solo alcanza proyectos y boards de los que eres propietario, miembro o administrador.
| Método | Ruta | Descripción | Acceso necesario |
|---|---|---|---|
| GET | /projects | Listar los proyectos a los que tienes acceso | Cualquier clave |
| GET | /projects/:token/boards | Listar los boards de un proyecto | Viewer |
| GET | /boards/:boardid | Obtener un board con sus estados e historias | Viewer |
| GET | /boards/:boardid/statuses | Listar los estados de un board | Viewer |
| GET | /boards/:boardid/stories | Listar las historias de un board, opcionalmente filtradas por estado o asignado | Viewer |
| GET | /boards/:boardid/stories/:storyid | Obtener una historia | Viewer |
| POST | /boards/:boardid/stories | Crear una historia | Editor |
| PATCH | /boards/:boardid/stories/:storyid | Actualizar los campos de una historia | Editor |
| POST | /boards/:boardid/stories/:storyid/status | Cambiar el estado de una historia | Editor o contributor |
| DELETE | /boards/:boardid/stories/:storyid | Eliminar una historia | Editor |
| POST | /boards/:boardid/stories/:storyid/comments | Añadir un comentario a una historia | Commenter |
| Cuenta, facturación y facturas | |||
| GET | /account | Obtener tu cuenta: plan, límites de uso del plan gratuito y datos de facturación | Cualquier clave |
| GET | /invoices | Listar tus facturas | Cualquier clave |
| GET | /invoices/:invoiceid · …/pdf | Obtener el detalle de una factura, o descargarla en PDF | Cualquier clave |
| Banco de horas | |||
| GET | /projects/:token/hourbank · …/transactions | Obtener la configuración y el saldo actual del banco de horas de un proyecto, o su libro de transacciones | Viewer |
| POST | …/hourbank/settings · …/entries | Configurar el banco de horas de un proyecto, o añadirle una compra/ajuste | Propietario del proyecto |
| Equipo | |||
| GET | /team | Listar tu equipo interno en todos tus proyectos y feature boards | Cualquier clave |
| Feature boards | |||
| GET | /featureboards | Listar los feature boards a los que perteneces | Miembro del board |
| POST | /featureboards | Crear un feature board | Plan de pago |
| GET | /featureboards/:boardid | Obtener un feature board con sus features, votos, comentarios y miembros | Miembro del board |
| POST | …/features · …/vote · …/comments | Enviar una feature request, votarla, o añadir un comentario | Miembro del board |
| PATCH POST DELETE | …/features/:featureid · …/status | Actualizar, fijar el estado de, o eliminar una feature request | Administrador del board |
| DELETE | …/comments/:commentid | Eliminar un comentario de una feature request | Autor del comentario o administrador del board |
| POST DELETE | /featureboards/:boardid/members · …/:userid/admin · …/:userid/external | Añadir, ascender/descender, reclasificar o eliminar un miembro del board | Administrador del board |
«Editor o contributor» también incluye a los developers, que solo pueden cambiar el estado, no editar el texto de la historia.
Ejemplo:
curl https://scrumbo.com/api/v1/boards/123/stories \
-H "Authorization: Bearer sbo_your_key_here"
curl -X POST https://scrumbo.com/api/v1/boards/123/stories \
-H "Authorization: Bearer sbo_your_key_here" \
-H "Content-Type: application/json" \
-d '{"subject": "New story", "story": "Details go here"}'Parámetros
Los cuerpos de las peticiones son JSON. Todos los parámetros siguientes los aceptan tanto la API REST como la herramienta MCP correspondiente.
Parámetros de ruta
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
:token |
string | Sí | Token del proyecto, tal como lo devuelve GET /projects. |
:boardid |
integer | Sí | Id numérico del board, tal como lo devuelve GET /projects/:token/boards. |
:storyid |
integer | Sí | Id numérico de la story, único dentro de su board. |
Parámetros de consulta
GET /boards/:boardid/stories
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
status |
string | No | Devuelve solo las stories en este estado. Al filtrar no se distinguen mayúsculas y minúsculas. |
assigned |
string | No | Devuelve solo las stories con este nombre de persona asignada. Al filtrar no se distinguen mayúsculas y minúsculas. |
Campos de una story (crear y actualizar)
POST /boards/:boardid/stories · PATCH /boards/:boardid/stories/:storyid
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
subject |
string | Al crear | Título corto, máximo 500 caracteres. Obligatorio al crear; los valores más largos se rechazan. |
story |
string | No | Cuerpo de la story. Se permite HTML, pero se sanea en el servidor: las etiquetas y atributos no admitidos se eliminan. |
status |
string | No | Debe coincidir exactamente con uno de los estados del proyecto, incluidas mayúsculas y minúsculas. Al crear, un estado desconocido o ausente recurre al primer estado del board; al actualizar, un estado desconocido se rechaza. |
assigned |
string | No | Nombre de la persona asignada, texto libre. Es solo una etiqueta: no vincula la story con una cuenta de Scrumbo. |
requester |
string | No | Nombre de quien solicitó la story, texto libre. |
scope |
string | No | Etiqueta de alcance corta, máximo 100 caracteres. Los valores más largos se rechazan. |
comment |
string | No | Campo de texto libre heredado que se guarda en la propia story. No se muestra en la interfaz web: para añadir un comentario visible, usa el endpoint de comentarios de abajo. |
notify |
boolean | No | Envía un correo sobre este cambio a quienes siguen el board y la story. Por defecto es false. |
- Cualquier campo que no aparezca aquí se ignora en lugar de rechazarse.
- Una actualización debe incluir al menos uno de estos campos; solo cambian los campos que envíes.
- Vincular una story con una cuenta de Scrumbo (el selector de persona asignada) no está disponible a través de la API.
Mover una story
POST /boards/:boardid/stories/:storyid/status
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
status |
string | Sí | Estado de destino. Debe coincidir exactamente con uno de los estados del proyecto, incluidas mayúsculas y minúsculas. |
notify |
boolean | No | Envía un correo sobre este cambio a quienes siguen el board y la story. Por defecto es false. |
Añadir un comentario
POST /boards/:boardid/stories/:storyid/comments
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
comment |
string | Sí | Texto del comentario, en texto plano. Se escapa antes de guardarlo, así que el HTML se muestra literalmente en vez de interpretarse. |
name |
string | No | Nombre de autor que se muestra en el comentario. Por defecto, el nombre de la cuenta de la clave API. |
notify |
boolean | No | Envía un correo sobre este cambio a quienes siguen el board y la story. Por defecto es false. |
Las peticiones rechazadas devuelven el estado HTTP correspondiente (400, 403 o 404) y un cuerpo JSON:
{"error": "subject must be at most 500 characters"}Servidor MCP
Scrumbo incluye un servidor MCP independiente que expone la API REST como herramientas, para que un asistente compatible con MCP como Claude Desktop o Claude Code pueda usar tus boards directamente. Requiere Node.js 20 o posterior.
Descargar el servidor MCP (ZIP)
-
Descomprímelo e instala sus dependencias una vez:
unzip scrumbo-mcp.zip cd scrumbo-mcp npm install - Crea una clave API en tu página de cuenta y cópiala.
- Registra el servidor en tu cliente MCP, por ejemplo:
{
"mcpServers": {
"scrumbo": {
"command": "node",
"args": ["/absolute/path/to/scrumbo-mcp/index.js"],
"env": {
"SCRUMBO_API_KEY": "sbo_your_key_here",
"SCRUMBO_API_URL": "https://scrumbo.com/api/v1"
}
}
}
}Herramientas:
| Descripción | Acceso necesario |
|---|---|
list_projects | Cualquier clave |
list_boards, get_board, list_stories, get_story, list_statuses | Viewer |
add_comment | Commenter |
create_story, update_story, move_story, delete_story | Editor |
get_account, list_invoices, get_invoice, get_invoice_pdf, get_team | Cualquier clave |
get_hourbank, list_hourbank_transactions | Viewer |
save_hourbank_settings, add_hourbank_entry | Propietario del proyecto |
list_feature_boards, get_feature_board, create_feature, vote_feature, add_feature_comment | Miembro del board |
create_feature_board | Plan de pago |
update_feature, set_feature_status, delete_feature, add_feature_board_member, set_feature_board_member_admin, set_feature_board_member_external, remove_feature_board_member | Administrador del board |
delete_feature_comment | Autor del comentario o administrador del board |
Ten en cuenta
- Una clave tiene exactamente tu acceso — quien la tenga puede actuar en tu nombre dentro de ese alcance, así que trátala como una contraseña.
- Revoca una clave en cualquier momento desde tu página de cuenta; todo lo que la use deja de funcionar de inmediato.
- El propio servidor MCP no tiene acceso a la base de datos — es un cliente HTTP ligero que nunca tiene más privilegios que la clave que le proporcionas.