Tools disponibles
El MCP server de Whet expone tools repartidas en tres superficies:
- Core (8) — las primitives agent-native originales: pipelines, inbox, drafts, publish, X cookies, scraping.
- Sessions (18) — la superficie del canvas de drafting (snapshottear items upstream → generar variantes con overrides de LLM → exportar). Nuevas en U11.
- Dashboards (9) — read/write de los dashboards de analytics del workspace.
Los schemas que siguen vienen directo del código (apps/web/lib/mcp/tools/*); los cambios breaking se anuncian con bump del MCP server.
Todas las tools mutativas requieren
idempotency_key(16–128 chars) donde se indique — repetir con la misma key devuelve el mismo run/resultado.
Core tools (8)
| Tool | Propósito | Side effects |
|---|---|---|
start_draft | Inicia un draft a partir de un post existente. | Encola un run en el job runner. |
read_inbox | Lista el inbox de un pipeline. | Solo lectura. |
list_posts | Lista los posts raw de un pipeline. Paginado. | Solo lectura. |
diagnose_pipeline | Devuelve estado, errores y un suggested_action accionable. | Solo lectura. |
create_pipeline_from_intent | Crea un pipeline (o resume uno existente). | Persiste el pipeline + arranca el primer scrape. |
publish_artifact | Marca un artifact como publicado. | Mutativo, debe ir tras confirmación humana. |
connect_x_account | Conecta o rota una credencial de cuenta. Probe sincrónico. | Persiste/rota la credencial. |
scrape_url | Fetch + estructurado de una URL pública vía el servicio de scraping. | Persiste el resultado del scrape (y schema, si se generó). |
start_draft
Inicia un draft a partir de un post existente del inbox. El run se persiste y aterriza como artifact en estado review cuando el modelo termina; el agente puede pollearlo o suscribirse al webhook riff.ready.
| Campo | Tipo | Required | Descripción |
|---|---|---|---|
source_post_id | string | sí | ID del post source. tw_<id> para posts scrapeados, ws_<uuid> para webpage snapshots. |
style_reference | string (≤4000) | no | Guía de estilo libre que el modelo debe imitar. |
parent_artifact_id | string | no | Artifact padre (rf_<uuid> o bf_<uuid>) si este draft se encadena a uno previo. |
idempotency_key | string (16–128) | sí | Repetir con la misma key devuelve el mismo run. |
read_inbox
Lista el inbox del pipeline — drafts en review, refinements pendientes, runs flaggeados por diagnose.
| Campo | Tipo | Required | Descripción |
|---|---|---|---|
pipeline_id | string | sí | pp_<uuid> o uuid pelado. |
list_posts
Lista paginada de source posts ingestados con métricas de engagement (likes/replies/retweets/views).
| Campo | Tipo | Required | Descripción |
|---|---|---|---|
pipeline_id | string | sí | pp_<uuid> o uuid pelado. |
cursor | string | no | Cursor de paginación de un call previo. |
limit | number (1–100) | no | Tamaño de página. |
has_artifact | boolean | no | Filtra posts que ya tienen un artifact (true) o que no (false). |
diagnose_pipeline
Reporte estructurado de salud: runs trabados, credenciales faltantes, cool-downs del scraper, etc. Cada issue trae suggested_action y suggested_endpoint.
| Campo | Tipo | Required | Descripción |
|---|---|---|---|
pipeline_id | string | sí | pp_<uuid> o uuid pelado. |
create_pipeline_from_intent
Create-or-resume idempotente de un pipeline que trackea un handle de X. Devuelve la referencia del pipeline, arranca el primer scrape.
| Campo | Tipo | Required | Descripción |
|---|---|---|---|
handle | string | sí | Handle a trackear (con o sin @). |
intent | string (10–2000) | sí | Descripción libre de por qué importa este handle. |
tone | enum | no | neutral | punchy | analytical | snarky | formal. |
idempotency_key | string (16–128) | sí | Repetir con la misma key resume el mismo pipeline. |
Esta tool no acepta
source,kind,scopeniauto_fanout. Defaults:source=x,kind=prose,scope=per_post. Para otros shapes usá el CLI.
publish_artifact
Marca un artifact como publicado. El publish real al destino (cuando el pipeline opta in vía auto-fanout) se maneja downstream; esta tool solo registra el go-ahead del operador.
| Campo | Tipo | Required | Descripción |
|---|---|---|---|
artifact_id | string | sí | rf_<uuid> o bf_<uuid> o uuid pelado. |
idempotency_key | string (16–128) | sí | Repetir con la misma key es no-op. |
El artifact debe estar en review/ready — llamarlo en otro estado devuelve error con suggested_action: 'fetch_artifact'.
connect_x_account
Conecta o rota una credencial de cuenta. El probe corre sincrónicamente y la respuesta embebe el resultado.
| Campo | Tipo | Required | Descripción |
|---|---|---|---|
handle | string | sí | Handle sin @, forzado a lowercase server-side. |
auth_token | string | sí | Valor de la cookie auth_token. |
ct0 | string | no | Cookie ct0 opcional — el scraper la deriva si se omite. |
proxy_url | string (URL) | no | URL de proxy SOCKS/HTTPS opcional para esta cookie. |
idempotency_key | string (16–128) | sí |
scrape_url
Fetch de una URL HTTPS pública vía el servicio de scraping. El mode determina el parsing:
| Campo | Tipo | Required | Descripción |
|---|---|---|---|
url | string (HTTPS, ≤2048) | sí | URL target. |
mode | enum | no | markdown | css | llm | auto. Default auto (CSS primero, LLM como fallback). |
intent | string (1–2000) | no | Requerido para css/llm/auto salvo que se provea schema_id. |
schema_id | string | no | Reutilizar un schema generado previamente. |
Scrapes repetidos para el mismo par (url, intent) pegan al cache después del primer call.
Sessions tools (18)
El canvas de drafting: snapshotteás items upstream en una session, attacheás variantes con LLM y preset por variante, generás rounds, exportás. Ver Sessions para el modelo completo.
Lifecycle
| Tool | Params | Efecto |
|---|---|---|
session_create | name? | Crea un canvas vacío para el par (org, user) activo. Devuelve id + name. |
session_list | limit (1–50, default 20) | Lista sessions ordenadas por last_active_at desc, con conteos de items/variantes. |
session_get | sessionId | Carga la session completa: items, variantes con rounds, sources, activity reciente. |
session_update | sessionId, name (nullable) | Renombrar una session. |
session_delete | sessionId | Borra en cascada session + items + variantes + rounds + exports. Irreversible. |
Selection (items)
| Tool | Params | Efecto |
|---|---|---|
session_add_item | sessionId, upstreamItemId?, sourceId?, sourceKind, externalItemId?, title, snippet, capturedAt, metrics?, raw? | Snapshottea un item upstream (X post / webpage / RSS / custom) en la session. Snapshot inmutable. |
session_remove_item | sessionId, sessionItemId | Borra un item snapshotteado. El upstream queda intacto. |
session_clear_selection | sessionId | Remueve todos los items. Variantes y rounds quedan. |
Variants
| Tool | Params | Efecto |
|---|---|---|
session_add_variant | sessionId, presetId, userPresetId?, prompt, style, typeTag, llmCredentialId? | Agrega una variante con preset + prompt + style. Arranca en status=idle. |
session_update_variant | variantId, prompt?, style?, llmCredentialId? | Patchea la config de la variante. Omitir un campo lo deja sin cambios. |
session_remove_variant | variantId | Borra la variante. Cascada a rounds + exports. |
session_select_round | variantId, roundIndex | Cambia el round activo de la variante (base 0, clampea al rango válido). |
session_generate_variant | variantId, sessionId | Encola la generación con LLM. Devuelve cuando el round se generó o el status si todavía está queued. |
session_generate_all | sessionId | Encola generación para todas las variantes de la session. |
session_variant_rounds | variantId | Lista la historia de rounds (más viejos primero) sin cargar la session completa. |
Exports + presets
| Tool | Params | Efecto |
|---|---|---|
session_export_variant | sessionId, variantId, roundId?, format (default markdown) | Registra un evento de export (loguea session_export; alimenta el KPI EXPORTS 7D). |
session_save_preset | name, description, prompt, style, typeTag | Persiste la config de una variante como user preset nombrado (scopeado por org + user). |
Sources (solo lectura)
| Tool | Params | Efecto |
|---|---|---|
session_list_sources | — | Lista las sources conectadas al workspace (X handles, webpages) para el picker de session items. |
Dashboards tools (9)
Acceso read/write a los dashboards de analytics del workspace. Los widgets se validan contra el catálogo de datasets en escritura y se resuelven en ejecución.
| Tool | Params | Efecto |
|---|---|---|
dashboards_list | — | Lista los dashboards del workspace activo, ordenados por actualización más reciente. |
dashboards_get | id | Carga el dashboard + todos los widgets en orden de creación. No ejecuta los widgets. |
dashboards_create | name, description?, templateId?, layout? | Provisiona un dashboard nuevo. Con templateId, siembra widgets. |
dashboards_delete | id | Hard-delete del dashboard + cascada a los widgets. Solo el creador puede llamarlo. |
dashboards_create_widget | dashboardId, title, type (kpi/timeseries/donut/bar/topN/table), querySpec, position?, visualization? | Appendea un widget. Valida querySpec contra el catálogo de datasets. |
dashboards_update_widget | widgetId, title?, querySpec?, position?, visualization? | Patchea un widget. Re-valida querySpec. |
dashboards_delete_widget | widgetId | Remueve el widget + la entrada de layout que matchea. |
dashboards_list_datasets | — | Devuelve el catálogo: nombres de métricas, nombres de dimensiones, filters, buckets de groupBy por dataset. Incluye info de tenant scoping. |
dashboards_execute_widget | widgetId, timeRange? (override, no se persiste) | Corre el querySpec del widget por el resolver; devuelve QueryResult (current/previous/partial). |
Errores comunes
Todas las tools devuelven errores con shape { error: { code, message, suggested_action?, suggested_endpoint? } }. Códigos principales:
unauthorized— token inválido o revocado.not_found— el recurso no existe en el deployment.validation_failed— los params no cumplen el schema.messagete dice qué falta.state_conflict— el recurso no está en un estado válido para la operación.credential_missing/credential_dead— el scraper no tiene cookies usables. Combinar conconnect_x_account.
Los errores incluyen suggested_action cuando hay una acción concreta accionable por el agente sin intervención humana.