API

MCP server

Iterar expone un servidor MCP (Model Context Protocol) para que Claude.ai, Claude Desktop y Claude Code hablen directamente con tu roadmap: listar items, leer el contexto completo, redactar PRDs, mover estados y publicar changelog.

Endpoints

Endpoint	Transport	Uso
https://iterar.io/api/mcp	Streamable HTTP	Recomendado · Claude.ai web, Claude Desktop ≥ 0.7, Claude Code
https://iterar.io/api/mcp/sse	SSE legacy	Clientes MCP viejos

Opción A — Conectar con OAuth (recomendado)

No hace falta crear API keys ni pegar JSON. Funciona con Claude.ai web y los Claude Desktop / Code recientes.

En Claude.ai: Settings → Connectors → Add custom connector → pegás https://iterar.io/api/mcp y click Connect. Se abre Iterar, iniciás sesión y aprobás el acceso. Listo.

En Claude Code:

bash

claude mcp add iterar https://iterar.io/api/mcp --transport http

En Claude Desktop: Settings → Connectors → Add → URL above. (En versiones que aún no tienen UI de connector, usá el snippet de abajo:)
claude_desktop_config.json (OAuth)
json
```
{
  "mcpServers": {
    "iterar": {
      "transport": "http",
      "url": "https://iterar.io/api/mcp"
    }
  }
}
```

Cómo funciona el OAuth

Cada cliente se auto-registra vía Dynamic Client Registration (RFC 7591). Cuando clickeás Connect, te redirige a iterar.io/oauth/authorize, te pide login y consent, y te devuelve un access token bound al cliente. Vos podés revocarlo en cualquier momento desde /dashboard/[slug]/settings/mcp.

Opción B — API key (legacy fallback)

Para clientes que aún no soportan OAuth: generás una key en /dashboard/[slug]/settings/api-keys (empieza con lpbk_sk_), y la pegás en el header Authorization.

No las publiques

Estas keys dan acceso a tus proyectos. Nunca las commitees a un repo. Si una se filtra, revocala desde el dashboard.

claude_desktop_config.json (Streamable HTTP + API key)

json

{
  "mcpServers": {
    "iterar": {
      "transport": "http",
      "url": "https://iterar.io/api/mcp",
      "headers": {
        "Authorization": "Bearer lpbk_sk_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

SSE legacy

Si tu cliente solo soporta SSE (transport legacy):

claude_desktop_config.json (SSE legacy)

json

{
  "mcpServers": {
    "iterar": {
      "transport": "sse",
      "url": "https://iterar.io/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer lpbk_sk_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Tools disponibles (68 totales)

Todas las tools son gratis: no consumen créditos. Las destructivas (delete, revoke) requieren confirm: true explícito para que un agente no las dispare por error. Esta lista se genera sola desde el código — siempre refleja las tools reales del servidor.

Roadmap & feedback — lectura y acciones core

Tool	Descripción
`list_projects`	Devuelve los proyectos de Iterar del usuario (id, slug, nombre, plan flags).
`list_roadmap_items`	Lista items del roadmap de un proyecto, con filtros opcionales por estado, periodo (7d/30d/90d) y orden (votes\|recent).
`get_item_details`	Devuelve un item del roadmap con sus comentarios recientes y los feedbacks (quotes) que lo originaron.
`get_top_requests`	Devuelve los items más votados del proyecto en el periodo indicado. Ideal para 'qué hago próximo?'.
`update_item_status`	Cambia el estado de un item del roadmap (idea\|under_review\|planned\|in_progress\|completed\|closed) y deja registro auditable. Si pasas changelog_note y el nuevo estado es 'completed', también publica una entrada en el changelog vinculada al item.
`post_internal_note`	Agrega un comentario interno (solo visible en el dashboard del founder) en un item del roadmap.
`get_credits_balance`	Devuelve el saldo de créditos del usuario (plan + extra).

Roadmap items — CRUD y power-user

Tool	Descripción
`create_roadmap_item`	Crea un item de roadmap manualmente (sin pasar por la pipeline de feedback). Útil para ideas que el founder ya tiene en su cabeza o que vienen de otros canales. Ai_generated=false.
`update_roadmap_item`	Edita título, descripción, categoría, ETA, esfuerzo estimado o notas internas. Solo los campos que pasás se actualizan. Para cambiar el estado usá `update_item_status`.
`delete_roadmap_item`destructiva	Borra un item de roadmap definitivamente. Requiere `confirm: true` explícito. Los votos y comments del item cascadean. Los feedbacks linkeados quedan con `roadmap_item_id=null` (no se pierden).
`set_item_pinned`	Marca o desmarca un item como pinned. Los items pinned suben al tope de su columna en el kanban del dashboard.
`set_item_priority`	Setea la prioridad del item entre 0 y 10. 0 (default) hace que el item rankee por debajo de los que sí tienen prioridad explícita.
`set_item_blocked_by`	Reemplaza la lista de items que bloquean a este. Cada blocker debe pertenecer al mismo proyecto. Pasá `[]` para limpiar.
`merge_items`	Mueve votos, comments y feedbacks del item source al target, recalcula vote_count del target, y deja el source con status='merged' (la URL sigue funcionando). Útil cuando Claude detecta que dos items son la misma feature.
`add_comment`	Postea un comment en un item. `is_internal: true` (default) lo deja visible solo en el dashboard del founder. `is_internal: false` lo publica en el roadmap público.

Boards

Tool	Descripción
`list_boards`	Devuelve todos los boards del proyecto (ordenados por `order_index`, luego por fecha). Incluye `is_default` y `is_public` para que el agente sepa cuál mostrar.
`create_board`	Crea un nuevo board. Si `slug` no se pasa o ya existe en el proyecto, se auto-genera con sufijo (-2, -3…). El primer board del proyecto se marca como default automáticamente; si pasás `is_default=true` en uno nuevo, el default anterior se desmarca.
`update_board`	Edita nombre, slug, descripción, visibilidad pública o reorder de un board. Si pasás `is_default=true` el board anterior pierde el flag automáticamente.
`delete_board`destructiva	Borra un board. Los items que lo referenciaban se reasignan al board pasado en `reassign_to_board_id`, o quedan con `board_id=null` (caen al board default). Si borrás el default, se promueve el board más viejo como nuevo default. Requiere `confirm: true`.
`set_item_board`	Mueve un item de roadmap a otro board del mismo proyecto. Pasá `board_id: null` para desasignarlo (cae al default).

Feedbacks & bandeja IA

Tool	Descripción
`list_pending_ai_actions`	Devuelve las acciones que la IA propuso y están esperando revisión del founder (dedup, crear item, marcar spam, sugerir status change, merge). Incluye el `proposal` con la justificación.
`approve_ai_action`	Ejecuta la propuesta de una acción IA pendiente: crea/dedupea items, ajusta votos, marca feedbacks como procesados, cambia estados, hace merges. Idempotente: si la acción ya no está en `pending`, devuelve `Ya procesada`.
`reject_ai_action`	Marca una acción IA como `rejected` sin ejecutarla. Útil cuando la IA se equivocó y el founder no quiere ese efecto. La fila queda en el log de auditoría.
`list_feedbacks`	Lista los feedbacks crudos del proyecto, con filtros opcionales por status (pending\|processed\|spam\|merged\|pending_credits\|rejected), category (feature\|bug\|...) y `search` (ILIKE sobre raw_content y submitter_email). Ordenados por created_at desc.
`get_feedback`	Devuelve el feedback completo (raw_content, submitter_email, language, category, status, roadmap_item_id, metadata, IP, user-agent, timestamps).
`mark_feedback_spam`	Marca un feedback como `spam` y setea `processed_at` al ahora. No cuesta créditos. Útil cuando la IA no lo agarró y querés que el founder lo flagee a mano.
`assign_feedback_to_item`	Linkea un feedback a un item de roadmap existente: lo marca como `processed`, setea `roadmap_item_id`, inserta un voto `ai_dedup` (idempotente — si ya existía un voto (item, feedback) no se duplica) y recalcula el `vote_count` del item desde la tabla canónica `votes`.
`delete_feedback`destructiva	Borra un feedback definitivamente. Requiere `confirm: true` explícito. Si solo querés ocultarlo en el inbox, preferí `mark_feedback_spam`. Borrar un feedback NO borra el item de roadmap al que está linkeado.
`submit_test_feedback`	Inserta un feedback con `submitter_metadata.source = 'mcp_test'` y dispara el pipeline IA (clasificación + dedup + spam-detection). Si el owner no tiene créditos, el feedback queda en `pending_credits` sin disparar la pipeline. Devuelve `feedback_id` para chequear el resultado luego con `get_feedback`.

Changelog & widget

Tool	Descripción
`create_changelog_entry`	Crea una entrada en el changelog del proyecto (publicada o draft). Tags válidos: added \| fixed \| improved \| security \| breaking \| deprecated.
`list_changelog_entries`	Lista las entradas del changelog de un proyecto (publicadas y drafts), ordenadas por published_at desc nulls last. Opcional `since` (ISO date) para filtrar.
`update_changelog_entry`	Actualiza una entrada del changelog (título, contenido, tags, items relacionados, o publish/unpublish). Bumpea updated_at.
`mark_item_completed_and_announce`	Marca un item del roadmap como completado Y publica el changelog en una sola operación — ideal para Claude Code cuando termina de implementar una feature.
`delete_changelog_entry`destructiva	Borra una entrada del changelog (publicada o draft) definitivamente. Requiere `confirm: true` explícito. Si solo querés despublicar, usá `update_changelog_entry` con `publish: false`.
`get_widget_config`	Devuelve la configuración actual de ambos widgets (feedback + changelog) del proyecto: colores, posición, tags visibles, categorías, allowed_origins, trigger_mode, etc. Útil para revisar antes de aplicar cambios.
`get_widget_install_snippet`	Devuelve el `<script>` listo para pegar en el sitio del usuario. Acepta `kind: 'feedback' \| 'changelog'`. Para el changelog en modo `custom` también incluye el ejemplo de botón con `data-iterar-trigger='changelog'`.
`update_feedback_widget`	Edita los settings del widget de feedback (mode, position, language, primary_color, theme_mode 'dark'/'light'/'auto', background_color, text_color, border_radius, email_mode, visible_categories, questions). Solo los campos que pasás se actualizan. `background_color`/`text_color`: pasá `null` para volver al default del modo.
`update_changelog_widget`	Edita los settings del changelog widget (enabled, position, limit, show_unread_dot, bell_label, visible_tags, trigger_mode + theme_mode/primary_color/background_color/text_color). `trigger_mode='floating'` muestra la campana en una esquina; `'custom'` no monta UI y el host wira su propio botón con `data-iterar-trigger='changelog'`. Los campos de theme aceptan `null` para 'heredar del widget de feedback'.
`update_allowed_origins`	Reemplaza la lista de origins permitidos del widget. Acepta dominios exactos ('app.foo.com'), wildcards ('*.foo.com') o URLs completas. Sin entradas = permisivo (allowlist abierto).

Branding & settings del proyecto

Tool	Descripción
`update_branding`	Cambia el color primario (#RRGGBB) y/o el logo URL del proyecto. El color se propaga al widget, al portal público y al dashboard via CSS var.
`update_project`	Edita nombre, descripción, slug (URL del portal), is_public, ai_mode ('suggested' \| 'auto'), y los thresholds de auto-promoción (auto_threshold_under_review, auto_threshold_planned). Cambios de slug devuelven `new_slug`.
`update_custom_domain`	Setea el dominio propio del portal público del proyecto (ej. 'feedback.tu-marca.com'). El middleware resuelve hostnames a /r/[slug] automáticamente. Pasá `null` o '' para desactivar.
`update_multilingual`	Activa o desactiva la traducción on-demand del portal público + setea el `default_locale` ('es' \| 'en' \| 'pt' \| 'fr'). Cuando está activo, items se traducen con Gemini Flash y se cachean en `item_translations`.
`update_ai_persona`	Setea el tono ('formal' \| 'casual' \| 'tecnico'), la densidad de emojis ('none' \| 'light' \| 'rich') y opcionalmente el nombre de la IA. Se inyecta en los prompts del pipeline de clasificación.

Analytics, digests & API keys

Tool	Descripción
`get_project_analytics`	Devuelve los KPIs principales del proyecto: feedbacks totales y en período (con breakdown por status y categoría), items totales y completados/in_progress (con breakdown por status), y total de votos en el período. `period`: 7d\|30d\|90d\|all (default 30d).
`get_sentiment_trend`	Devuelve buckets diarios (UTC) con cantidad de feedbacks positivos/neutrales/negativos en los últimos `days` (1..365, default 30). Días sin actividad vienen en cero, no faltan.
`get_top_voters`	Devuelve los voters más activos sobre items del proyecto, agrupados por email (con fallback a fingerprint cuando son anónimos). `period`: 7d\|30d\|90d\|all (default 30d), `limit` 1..100 (default 10).
`get_changelog_stats`	Devuelve totales del changelog: entries totales, publicadas, publicadas en el período y breakdown por tag (added/fixed/improved/security/breaking/deprecated). `period`: 7d\|30d\|90d\|all (default 30d).
`list_digests`	Lista los weekly digests del proyecto (ordenados por period_start desc). Incluye summary JSON (counts) y delivered_at. Para el markdown completo usá `get_digest`.
`get_digest`	Devuelve un weekly digest completo, incluyendo `content_markdown` (la nota que arma la IA) y el `summary` JSON con métricas.
`generate_digest_now`	Dispara `deliverWeeklyDigest(project_id, { force })` para regenerar el digest de la semana actual (lunes UTC..). `force: true` (default) reescribe aunque exista una entrada delivered. Devuelve `delivered`, `digest_id` y `skipped_reason` si aplica.
`list_api_keys`	Lista las API keys del usuario autenticado. Filtros opcionales: `project_id` (slug o UUID) limita a las scoped a ese proyecto; `include_revoked` (default true) muestra/oculta las revocadas. Nunca devuelve el plaintext — solo `key_prefix`.
`create_api_key`	Genera una nueva API key (`lpbk_sk_*`) y devuelve el plaintext UNA SOLA VEZ. Si `project_id` se pasa, la key queda scoped a ese proyecto (no podrá ver/editar otros del mismo usuario). Si es `null` o se omite, la key tiene acceso a todos los proyectos del usuario. Guardá el plaintext apenas lo recibas — no se puede recuperar después.
`revoke_api_key`destructiva	Marca una API key como revocada (`revoked_at = now()`). La key deja de autenticar inmediatamente. Requiere `confirm: true`. Es irreversible — no hay un `unrevoke`.

Encuestas (feature-vote)

Tool	Descripción
`create_survey`	Crea una encuesta de votación de ideas con 2+ opciones. Se muestra una sola vez a cada visitante con el mismo widget de Iterar. `ask_email`: no\|optional\|required (default optional). `activate: true` la deja activa al crear (falla si ya hay otra activa).
`list_surveys`	Lista todas las encuestas del proyecto (draft\|active\|closed) con sus opciones, conteo de votos por opción y total.
`get_survey_results`	Devuelve una encuesta con sus opciones, los votos por opción y el total de respuestas (conteo canónico).
`activate_survey`	Pone una encuesta en estado `active` para que el widget la muestre. Solo puede haber UNA encuesta activa por proyecto: si ya hay otra, devuelve un error pidiendo cerrarla primero.
`end_survey`	Cierra una encuesta (status `closed`, setea `closed_at`). El widget deja de mostrarla. Después podés marcar la ganadora con `set_survey_winner`.
`set_survey_winner`	Marca cuál opción ganó la encuesta (la opción debe pertenecer a la encuesta). Habilita `promote_survey_winner` y `notify_survey_voters`.
`promote_survey_winner`	Crea un item de roadmap (status `planned`, ai_generated=false) a partir de la opción ganadora y lo linkea a la encuesta. Idempotente: si ya se promovió, devuelve el item existente. Requiere una ganadora marcada.
`notify_survey_voters`	Envía un email a quienes votaron la opción ganadora y dejaron email. Incluye link al roadmap si la ganadora fue promovida. Idempotente (ledger 24h) y setea `voters_notified_at`. Requiere una ganadora marcada.
`delete_survey`destructiva	Borra una encuesta y todos sus votos/opciones (cascade) definitivamente. Requiere `confirm: true` explícito.

Ejemplo de conversación

claude code session