Referencia de herramientas
Cada herramienta que expone el servidor MCP de PostNext, con sus entradas, estructura de retorno y un ejemplo listo para copiar y pegar.
https://mcp.postnext.io/apiPOST https://mcp.postnext.io/apiAutenticación
Cada petición a https://mcp.postnext.io/api necesita una cabecera Authorization con un token Bearer. Tienes dos formas de obtener uno.
OAuth (recomendado para clientes de IA)
Los clientes de IA ejecutan Dynamic Client Registration en la primera conexión y guían al usuario por una pantalla de consentimiento OAuth. La página /mcp/connect lo hace automáticamente. Tu cliente recibe un token de acceso de 30 días.
Clave de API
Para scripts y CI, genera una clave de API personal en la app de PostNext en Cuenta → Claves de API. La clave empieza por apikey_ y se presenta como un token Bearer como cualquier otro.
Endpoint
Todas las llamadas a herramientas van a un único endpoint JSON-RPC 2.0 sobre HTTPS POST.
Herramientas
list_scheduled_posts
Lista tus publicaciones programadas (en cola para publicar, aún no enviadas).
Argumentos
limitfromDevuelve
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
limitDevuelve
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, providerId, 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
platformwindowDaysDevuelve
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
platformcontentchannelNameproviderIdmediaUrlsclientRequestIdDevuelve
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 Plan de pago
Actualiza un borrador existente. Se debe proporcionar al menos content o mediaUrls.
Argumentos
postIdcontentmediaUrlsclientRequestIdDevuelve
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
platformDevuelve
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 con un timestamp futuro. Idempotente dentro de ±60s de deriva; rechaza intentos de reprogramación a otra hora sin cancelar primero. Cuenta para las publicaciones mensuales del plan (plan gratuito: 10, compartidas con la app); cada publicación cuenta una vez, así que reprogramarla tras cancelarla o tras una publicación fallida no vuelve a contar.
Argumentos
postIdscheduledAtDevuelve
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
postIdDevuelve
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
postIdDevuelve
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
postIdDevuelve
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
querystatusplatformlimitDevuelve
Un objeto con posts: [{postId, status, platforms, snippet, scheduledAt, updatedAt}]. El snippet contiene el contexto coincidente con puntos suspensivos 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
teamIdDevuelve
Un objeto con teamId, teamName, persisted (true si OAuth, false si clave de API) 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 usar herramientas que hacen cambios, para saber si la llamada se bloqueará.
Argumentos
Sin argumentos.
Devuelve
Un objeto con tier, tierDisplayName, isPaid, isTrial, limits (channels/storage/aiCalls cada uno como {limit, current, exceeded}; posts como {limit, allowed, current}, donde current es el número de este mes, o null si no se pudo leer) 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 de una publicación en cada plataforma a la que se envió. Twitter devuelve me gusta, retuits, respuestas e impresiones; Instagram devuelve me gusta y comentarios. LinkedIn, Threads y TikTok solo devuelven el estado de publicación y la URL (la recogida de interacción llegará en una versión posterior). Un total normalizado suma las métricas de las plataformas que las han 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 qué pasó con una publicación programada: estado en la cola, éxito o error por plataforma, tiempo de procesamiento y el job id del proceso. Devuelve isScheduled=false para publicaciones que existen como borrador pero nunca pasaron a la cola de publicación, con una pista que remite 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 Plan de pago
Actualiza el perfil de marca activo del usuario. Campos permitidos: bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Cualquier otro se descarta sin aviso. Resuelve "activo" primero como el perfil predeterminado del equipo y después 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 Plan de pago
Recomienda las N mejores franjas (día de la semana, hora) para la próxima publicación en una plataforma, según los últimos 90 días. Twitter e Instagram se ordenan por interacción por publicación; LinkedIn, Threads y TikTok solo por frecuencia de publicación. Las horas van en la zona horaria IANA indicada (UTC por defecto). Requiere un plan de pago.
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 franjas recomendadas 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.
providerId El providerId de la cuenta, de list_connected_accounts. No cambia cuando cambia el nombre de usuario, así que pásalo junto con channelName o en su lugar.
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 las etiquetas de caso de uso que coincidieron. Gratis en todos los planes (función de descubrimiento).
Argumentos
Todos opcionales. Llámalo sin argumentos para ver todas las herramientas disponibles.
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 y currency.
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}}}
import_chat_file
Solo en ChatGPT. Guarda en tu biblioteca las imágenes y los vídeos adjuntos en el chat, listos para create_post_draft. ChatGPT entrega cada archivo como un enlace temporal; PostNext lo descarga una vez por HTTPS y comprueba en el propio archivo que es una imagen o un vídeo. Hasta 10 archivos por llamada, 50 MB cada uno, que cuentan para el almacenamiento de tu plan (10 MB en total en el plan gratuito).
Argumentos
files Lo rellena ChatGPT con los archivos adjuntos en el chat: download_url y file_id, y opcionalmente mime_type y file_name. Hasta 10. Los demás clientes suben archivos con request_asset_upload.
Devuelve
Un objeto con files (assetId, url, sizeBytes, mimeType y fileName de cada archivo guardado) y failed (fileName y reason de cada archivo que no se pudo guardar). Si no se pudo guardar ningún archivo, la llamada devuelve en su lugar el error del primero.
Ejemplo
{"jsonrpc":"2.0","method":"tools/call","id":35,
"params":{"name":"import_chat_file",
"arguments":{"files":[{"download_url":"https://files.oaiusercontent.com/...","file_id":"file_abc123"}]}}}
Recursos MCP
Los recursos son contexto de solo lectura que el cliente puede obtener con el método MCP resources/read. Claude los carga al inicio de cada conversación, así tiene contexto de cuenta/equipo/marca sin que tengas que repetirlo.
postnext://account/summary
Email y nombre de usuario de la cuenta (para que Claude confirme con qué cuenta trabaja), plan, créditos de IA usados / límite, número de borradores, número de programadas y número de canales conectados. Cada número tiene un máximo de 100 para que cargue rápido.
postnext://channels/connected
Misma forma que el resultado de list_connected_accounts; se expone como recurso para que Claude lo cargue una vez al inicio de la conversación (sin una llamada extra a una herramienta).
postnext://brand-profiles/active
El perfil de marca activo del usuario (el predeterminado del equipo o, si no hay, el primer perfil propio). Devuelve solo los campos útiles para un LLM: bio, expertiseAreas, personalityTraits, brandVoice, mainThemes, audienceSize, preferredHashtags.
postnext://teams/current
Metadatos del equipo actual (teamId, teamName) más totalTeamsAvailable. Combina con list_teams + set_current_team para cambiar.
Flujos predefinidos
Atajos del menú slash que orquestan varias herramientas. Elige uno y deja que tu asistente de IA te guíe paso a paso, pidiendo confirmación antes de cualquier cambio.
/weekly-plan
Lee el perfil de marca, los canales conectados y la cola, y propone 5-10 borradores repartidos de lunes a viernes.
/draft-thread
Redacta un hilo de 5-10 publicaciones para Twitter o Threads sobre un tema o URL que tú indiques, con la voz de tu marca.
/audit-queue
Repasa los próximos 7 días de publicaciones programadas y detecta duplicados, saturación de plataformas y huecos.
/channel-sweep
Compara los canales conectados con los compatibles y sugiere cuáles conectar o actualizar.
Descubrimiento y endpoints OAuth
Metadatos conformes a estándares para que cualquier cliente MCP pueda autoconfigurarse.
GET /.well-known/oauth-protected-resource/api— RFC 9728GET /.well-known/oauth-authorization-server— RFC 8414GET /oauth/.well-known/openid-configuration— OIDCPOST /oauth/reg— Dynamic Client Registration (RFC 7591)GET /oauth/auth— Authorize (PKCE-S256 required)POST /oauth/token— Token exchange
Código abierto
Las recetas listas para pegar y una referencia para desarrolladores están en nuestro repositorio público de documentación. Con licencia MIT; se aceptan pull requests. github.com/postnextio/postnext-mcp
MCP de redes sociales para Claude, ChatGPT y cualquier agente de IA
El servidor MCP de redes sociales de PostNext deja que Claude, ChatGPT y cualquier agente de IA planifiquen, redacten y programen publicaciones. Los borradores esperan en tu calendario hasta que los programas.