Referencia de herramientas

list_scheduled_posts

Lista tus publicaciones programadas (en cola para publicar, aún no enviadas).

Argumentos

Devuelve

Un objeto con posts: [{id, platform, content, scheduledAt, status}]. Hasta limit resultados.

Ejemplo

curl -X POST https://mcp.postnext.io/api \
  -H "Authorization: Bearer apikey_xxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":1,
       "params":{"name":"list_scheduled_posts",
                 "arguments":{"limit":5}}}'

list_drafts

Lista tus borradores (aún no programados).

Argumentos

Devuelve

Un objeto con drafts: [{id, platform, content, updatedAt}]. Hasta limit resultados.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":2,
 "params":{"name":"list_drafts","arguments":{"limit":10}}}

list_connected_accounts

Lista las cuentas sociales conectadas a tu equipo.

Argumentos

Sin argumentos.

Devuelve

Un objeto con accounts: [{platform, handle, connected, lastSyncAt}].

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":3,
 "params":{"name":"list_connected_accounts","arguments":{}}}

get_account_healthPlan de pago

Obtén un resumen del estado de todas las plataformas conectadas.

Argumentos

Devuelve

Un objeto con windowDays, postsScheduled, postsPublished, postsFailed, un desglose byPlatform y topErrors[].

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":4,
 "params":{"name":"get_account_health",
           "arguments":{"windowDays":30}}}

create_post_draft

Crea un borrador nuevo. Los borradores no se publican automáticamente.

Argumentos

Devuelve

Un objeto con el nuevo borrador: {id, platform, content, status: "DRAFT", createdAt}.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":5,
 "params":{"name":"create_post_draft",
           "arguments":{"platform":"twitter",
                        "content":"Hello from MCP"}}}

update_post_draft

Actualiza un borrador existente. Se debe proporcionar al menos content o mediaUrls.

Argumentos

Devuelve

Un objeto con el borrador actualizado: {id, platform, content, mediaUrls, status, updatedAt}.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":6,
 "params":{"name":"update_post_draft",
           "arguments":{"postId":"",
                        "content":"Updated copy"}}}

connect_channel

Genera una URL de un solo uso que el usuario puede abrir para autorizar una nueva conexión de plataforma.

Argumentos

Devuelve

Un objeto con authUrl (enlace de un solo uso que el usuario abre para autorizar), expiresAt y platform.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":7,
 "params":{"name":"connect_channel",
           "arguments":{"platform":"linkedin"}}}

schedule_post

Mueve un borrador (estado DRAFT) a la cola de publicación BullMQ con un timestamp futuro. Idempotente dentro de ±60s de deriva; rechaza intentos de reprogramación a otra hora sin cancelar primero.

Argumentos

Devuelve

Un objeto con postId, scheduledAt (ISO), status: SCHEDULED.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":8,
 "params":{"name":"schedule_post",
           "arguments":{"postId":"",
                        "scheduledAt":"2026-05-10T09:00:00Z"}}}

cancel_scheduled_post

Cancela una publicación programada y la elimina de la cola de publicación. El borrador se conserva.

Argumentos

Devuelve

Un objeto con postId y status: CANCELLED.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":9,
 "params":{"name":"cancel_scheduled_post",
           "arguments":{"postId":""}}}

delete_draft

Elimina permanentemente un borrador. Rechaza publicaciones que no estén en estado DRAFT (usa cancel_scheduled_post para SCHEDULED).

Argumentos

Devuelve

Un objeto con postId y deleted: true.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":10,
 "params":{"name":"delete_draft",
           "arguments":{"postId":""}}}

get_post

Devuelve el PostGroup completo para un postId con contenido por plataforma + estado + timestamps.

Argumentos

Devuelve

Un objeto con postId, status, scheduledAt, createdAt, updatedAt y providers (mapa plataforma → contenido).

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":11,
 "params":{"name":"get_post",
           "arguments":{"postId":""}}}

search_posts

Búsqueda de subcadena (insensible a mayúsculas) en el contenido de publicaciones del equipo activo. Filtros: status, platform, limit (1-100, predeterminado 20).

Argumentos

Devuelve

Un objeto con posts: [{postId, status, platforms, snippet, scheduledAt, updatedAt}]. El snippet contiene el contexto coincidente con elipsis a ambos lados.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":12,
 "params":{"name":"search_posts",
           "arguments":{"query":"launch","limit":10}}}

list_teams

Devuelve los equipos que el usuario autenticado posee o administra, con el equipo activo marcado.

Argumentos

Sin argumentos.

Devuelve

Un objeto con currentTeamId y teams: [{teamId, teamName, isCurrent}].

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":13,
 "params":{"name":"list_teams","arguments":{}}}

set_current_team

Cambia el equipo activo para este token Bearer. El usuario debe ser miembro. Persistente en el documento del token OAuth; la mutación en sesión lo hace efectivo inmediatamente para herramientas posteriores en la misma conversación.

Argumentos

Devuelve

Un objeto con teamId, teamName, persisted (true si OAuth, false si API key) y un note opcional.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":14,
 "params":{"name":"set_current_team",
           "arguments":{"teamId":"team_xxxxx"}}}

get_plan_limits

Lee el nivel de suscripción actual del usuario y las cuotas por nivel (canales, almacenamiento, créditos de IA, publicación). Disponible en todos los planes. Útil antes de herramientas mutadoras para predecir si la llamada será bloqueada.

Argumentos

Sin argumentos.

Devuelve

Un objeto con tier, tierDisplayName, isPaid, isTrial, upgradeUrl, limits (channels/storage/aiCalls/posts cada uno como {limit, current, exceeded} o {limit, allowed}) y creditsAvailable ({total, subscriptionRemaining, purchasedBalance} o null).

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":15,
 "params":{"name":"get_plan_limits","arguments":{}}}

get_post_metrics

Obtiene métricas de interacción para una publicación publicada en cada plataforma a la que se envió. Twitter e Instagram devuelven métricas pobladas (likes, retweets/compartidos, comentarios/respuestas, impresiones); LinkedIn, Threads y TikTok devuelven solo estado de publicación y URL (la recolección de interacciones se aplaza a una versión posterior). Un resumen normalizado totals suma likes/comentarios/compartidos/impresiones de cualquier plataforma que haya reportado.

Argumentos

postId ID de publicación de PostNext obtenido de una llamada de listado.

Devuelve

Un objeto con postId, status, providers: [{platform, publishedPostId, publishedUrl, publishedAt, status, metrics}] y totals: {likes, comments, shares, impressions}. metrics es un objeto de contadores numéricos por plataforma, o null cuando la plataforma aún no recopila interacciones.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":16,
 "params":{"name":"get_post_metrics",
           "arguments":{"postId":""}}}

get_publish_status

Diagnostica una publicación programada: estado en cola, éxito/error por plataforma, tiempo de procesamiento y jobId del worker. Devuelve isScheduled=false para publicaciones que existen como borrador pero no fueron movidas a la cola de publicación, con un hint apuntando a schedule_post.

Argumentos

postId ID de publicación de PostNext obtenido de una llamada de listado.

Devuelve

Un objeto con postId, isScheduled, status, scheduledAt, publishedAt, platforms, processingTimeMs, jobId, topLevelError y results: [{platform, success, publishedPostId, publishedAt, error}]. Incluye hint cuando isScheduled es false.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":17,
 "params":{"name":"get_publish_status",
           "arguments":{"postId":""}}}

update_brand_profile

Actualiza el perfil de marca activo del usuario. Campos permitidos: bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Cualquier otro se descarta silenciosamente. Resuelve "activo" primero como default del equipo, luego como el primer perfil activo propio del usuario.

Argumentos

brandVoice Array de descriptores de voz de marca (p. ej. ["profesional", "conciso"]).

Other patchable fields: bio, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize.

Devuelve

Un objeto con profileId, name, updated: [nombres de campos parcheados] y los valores actuales de bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize tras el patch.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":18,
 "params":{"name":"update_brand_profile",
           "arguments":{"brandVoice":["professional","concise"]}}}

get_best_time_to_post Paid plan

Recomienda los mejores N slots (díaDeSemana, hora) para la próxima publicación en una plataforma, ordenados por engagement por publicación de los últimos 90 días. Twitter e Instagram devuelven scores ponderados por engagement; LinkedIn, Threads, TikTok ordenan solo por frecuencia. Tiempos en la zona horaria IANA indicada (UTC por defecto). Plan de pago requerido.

Argumentos

platform Plataforma social: twitter, instagram, linkedin, threads, o tiktok.

timezone Nombre de zona horaria IANA (p. ej. Europe/Madrid, America/New_York). Por defecto UTC.

topN Número de recomendaciones de slots a devolver (1-24, por defecto 5).

Devuelve

Un objeto con platform, timezone, sampleWindowDays, sampleSize, metricsAvailable y recommendations: [{dayOfWeek (1-7, Lun=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}]. Incluye hint para casos cold-start o sin métricas disponibles.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":19,
 "params":{"name":"get_best_time_to_post",
           "arguments":{"platform":"twitter","timezone":"Europe/Berlin","topN":5}}}

get_channel_analytics

Rendimiento agregado de un canal conectado, o de todos a la vez. Devuelve impresiones, alcance, me gusta, comentarios y tasa de interacción del periodo, el cambio frente al periodo anterior de la misma duración y la serie de seguidores. Sin platform, el total de todo el equipo. Para una sola publicación usa get_post_metrics; para planificar, get_best_time_to_post.

Argumentos

platform Plataforma social: twitter, instagram, linkedin, threads, o tiktok.

channelName Qué cuenta conectada, cuando la plataforma tiene más de una.

period Periodo del informe: 7d, 30d, 90d o all (por defecto 30d).

Devuelve

Un objeto con scope, period, totals, vsPrevious, coverage, dataThrough y followers, que incluye trackingSince, current, change y la serie.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":34,
 "params":{"name":"get_channel_analytics",
           "arguments":{"platform":"linkedin","period":"30d"}}}

search_tools

Busca en el catálogo de herramientas MCP por texto libre, categoría o intención. Devuelve categorías, requiresScope, descripciones de una línea y los tags de caso de uso que coincidieron. Disponible en todos los planes (interfaz de discovery).

Argumentos

All optional. Call with no arguments to list every available tool.

query Búsqueda de texto libre en nombres, descripciones y tags de uso de las herramientas.

category Filtra a una categoría: posts, accounts, analytics, brand, teams, discovery, other.

Devuelve

Un objeto con totalTools, matchCount, categories: [string[]] y tools: [{name, category, requiresScope, description, useCases, matchedOn: [name|category|description|use_case]}]. Incluye hint cuando no hay coincidencias o no hay filtro.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":20,
 "params":{"name":"search_tools",
           "arguments":{"query":"why did my post fail"}}}

get_plan

Plan y fechas de facturación: nivel, fecha de renovación, fin de la prueba y si la suscripción está marcada para cancelarse al final del periodo. Para cuotas y consumo, llama a get_plan_limits.

Argumentos

Sin argumentos.

Devuelve

Un objeto con tier, tierDisplayName, isPaid, isTrial, gated, subscriptionStatus, renewsAt, trialEndsAt, cancelAtPeriodEnd, currency y upgradeUrl.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":21,
 "params":{"name":"get_plan",
           "arguments":{}}}

upload_asset

Subida de una imagen o un vídeo a la biblioteca en base64 directamente. Solo es fiable con archivos muy pequeños, de unos 8 KB o menos: si el contenido es mayor se trunca en silencio en los argumentos de la herramienta y se guarda un archivo corrupto. Para cualquier cosa más grande, usa request_asset_upload.

Argumentos

filename Nombre del archivo con su extensión, hasta 255 caracteres.

contentType Tipo MIME del archivo, de la lista permitida de imagen y vídeo.

base64 Los bytes del archivo, codificados en base64. Mantenlo muy pequeño y lee antes el aviso de arriba.

Devuelve

Un objeto con assetId, url, sizeBytes y mimeType. Pasa la url a create_post_draft como mediaUrls.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":22,
 "params":{"name":"upload_asset",
           "arguments":{"filename":"logo.png","contentType":"image/png","base64":"iVBORw0KGgo..."}}}

request_asset_upload

La vía de subida recomendada, para imágenes y vídeos de cualquier tamaño. Dos pasos: llama a esta herramienta para obtener una URL prefirmada y un comando curl listo para usar, y envía después el archivo con PUT a esa URL. La respuesta del PUT trae la URL final del recurso.

Argumentos

filename Nombre del archivo con su extensión, hasta 255 caracteres.

contentType Tipo MIME del archivo, de la lista permitida de imagen y vídeo.

sizeBytes Tamaño exacto del archivo en bytes, se usa para firmar la subida.

Devuelve

Un objeto con uploadId, uploadUrl, uploadToken, expiresInSeconds e instructions con el comando PUT exacto.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":23,
 "params":{"name":"request_asset_upload",
           "arguments":{"filename":"clip.mp4","contentType":"video/mp4","sizeBytes":4194304}}}

get_latest_blog_post

Si el equipo tiene un blog de WordPress conectado, además de un extracto de la entrada más reciente. Solo lectura y sin coste en créditos. Llámala antes de create_blog_plan o test_blog_connection para ver qué hay ya configurado.

Argumentos

Sin argumentos.

Devuelve

Un objeto con blogConnected, un resumen de la integración sin credenciales y latestPost con su título, extracto, estado y URL publicada.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":24,
 "params":{"name":"get_latest_blog_post",
           "arguments":{}}}

list_blog_plans

Lista los planes de blog del equipo, del más reciente al más antiguo, con estado, número de temas por estado, créditos reservados y un enlace al panel. Solo lectura y sin coste en créditos.

Argumentos

limit Número máximo de planes devueltos (1-50, por defecto 20).

status Filtrar por estado: generating, active, paused, completed, cancelled o failed.

Devuelve

Un objeto con plans y total. Cada plan incluye su id, estado, número de temas y el enlace al panel.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":25,
 "params":{"name":"list_blog_plans",
           "arguments":{"status":"active","limit":10}}}

create_blog_plan Paid plan

Crea un plan de contenido de blog para un perfil de marca. Los temas se generan de forma asíncrona, así que el plan vuelve enseguida en estado generating: consulta list_blog_plans para ver el progreso. En los planes Business y Teams las entradas además se generan y se publican en un blog de WordPress conectado.

Argumentos

startDate Primer día que cubre el plan, en formato YYYY-MM-DD.

planDays Cuántos días cubre el plan (1-30, por defecto 7).

brandProfileId Perfil de marca para el que se planifica. Por defecto, el perfil activo del equipo.

integrationId Qué blog conectado usar, cuando el equipo tiene más de uno.

autoPublish Publicar automáticamente en el blog conectado las entradas generadas (Business y Teams).

Devuelve

Un objeto con planId, status, startDate, planDays, brandProfileId, integrationId, topicCount y dashboardUrl.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":26,
 "params":{"name":"create_blog_plan",
           "arguments":{"startDate":"2026-10-01","planDays":14,"autoPublish":true}}}

test_blog_connection Paid plan

Comprueba que el blog de WordPress conectado responde y que su token sigue siendo válido, y deja el resultado registrado en la integración. Devuelve la versión del plugin y lo que puede hacer.

Argumentos

integrationId Qué blog conectado usar, cuando el equipo tiene más de uno.

Devuelve

Un objeto con success, message, version, capabilities, integrationId y el status actualizado.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":27,
 "params":{"name":"test_blog_connection",
           "arguments":{}}}

list_mini_sites

Lista las páginas de biografía del equipo seleccionado, con su URL pública, si están publicadas y el progreso de configuración. Empieza aquí: el resto de herramientas de página de biografía usan el siteId que devuelve, y pueden omitirlo cuando el equipo tiene una sola página.

Argumentos

Sin argumentos.

Devuelve

Un objeto con sites, cada uno con id, slug, name, published, url, views y el progreso de configuración.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":28,
 "params":{"name":"list_mini_sites",
           "arguments":{}}}

get_mini_site

Lee una página de biografía completa: cabecera del perfil, iconos sociales, todos los bloques de contenido, metadatos SEO, tema y ajustes de auto-pin. Los textos largos se recortan a una vista previa de 300 caracteres y nunca se devuelven credenciales.

Argumentos

siteId Sobre qué página de biografía actuar. Omítelo cuando el equipo tiene una sola.

Devuelve

Un objeto con id, slug, published, url, header, socials, meta, theme, autoPin, campaign y el array blocks.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":29,
 "params":{"name":"get_mini_site",
           "arguments":{}}}

get_mini_site_analytics

Cómo rinde una página de biografía: visitas, clics, mejores enlaces, origen, dispositivo y país de los visitantes, y lecturas de rastreadores de IA, además de qué publicaciones generaron clics. Todas las cifras salvo las filas de atribución son contadores históricos y no del periodo: dilo al informar de los números.

Argumentos

siteId Sobre qué página de biografía actuar. Omítelo cuando el equipo tiene una sola.

attributionDays Ventana en días para la atribución de publicación a clic (1-90, por defecto 30).

Devuelve

Un objeto con viewsAllTime, clicksAllTime, topLinks, bySource, byDevice, byCountry, ai, attribution y attributionWindowDays.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":30,
 "params":{"name":"get_mini_site_analytics",
           "arguments":{"attributionDays":30}}}

add_mini_site_block

Añade un bloque a una página de biografía: link, featured, product, event, presave, episodio de podcast, booking, horarios, header, text, image o gallery. Los campos obligatorios cambian según el tipo. Esto modifica al instante una página visible para el público.

Argumentos

siteId Sobre qué página de biografía actuar. Omítelo cuando el equipo tiene una sola.

type Tipo de bloque que se añade, por ejemplo link, product, event, hours o gallery.

... Además, los campos propios de ese tipo de bloque, por ejemplo url, title, price o startDate.

Devuelve

Un objeto con el block guardado, el nuevo blockCount y alreadyExisted si ese mismo bloque ya estaba.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":31,
 "params":{"name":"add_mini_site_block",
           "arguments":{"type":"link","url":"https://example.com","title":"New single"}}}

update_mini_site_block

Modifica un bloque existente: el título o la URL de un enlace, el precio de un producto, la fecha de un evento, los horarios o el orden. Solo cambian los campos que envías, y el tipo de bloque no se puede cambiar. La respuesta devuelve el bloque tal como quedó guardado, así se ve cualquier valor rechazado.

Argumentos

siteId Sobre qué página de biografía actuar. Omítelo cuando el equipo tiene una sola.

blockId Id del bloque, tal como lo devuelve get_mini_site.

... Además, los campos propios de ese tipo de bloque, por ejemplo url, title, price o startDate.

Devuelve

Un objeto con el block tal como quedó guardado, la lista de campos actualizados y los ignorados.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":32,
 "params":{"name":"update_mini_site_block",
           "arguments":{"blockId":"blk_7f3a","title":"Updated title"}}}

remove_mini_site_block

Elimina un bloque de una página de biografía por su blockId, por ejemplo una fecha de gira ya pasada o un enlace de producto retirado. Llama antes a get_mini_site para localizar el id. Esto modifica al instante una página visible para el público.

Argumentos

siteId Sobre qué página de biografía actuar. Omítelo cuando el equipo tiene una sola.

blockId Id del bloque, tal como lo devuelve get_mini_site.

Devuelve

Un objeto con removed, el blockId y cuántos bloques quedan.

Ejemplo

{"jsonrpc":"2.0","method":"tools/call","id":33,
 "params":{"name":"remove_mini_site_block",
           "arguments":{"blockId":"blk_7f3a"}}}