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

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