Saltar al contenido

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.

URL del servidor MCPhttps://mcp.postnext.io/api
POST https://mcp.postnext.io/api

Autenticació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.

POST https://mcp.postnext.io/api

Herramientas

list_scheduled_posts

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

Argumentos

limitnumber ·opcional · default 20
Número máximo de resultados a devolver (1-100, por defecto 20).
fromstring (ISO 8601) ·opcional
Marca de tiempo ISO; devuelve solo las publicaciones programadas a partir de este momento.

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

limitnumber ·opcional · default 20
Número máximo de resultados a devolver (1-100, por defecto 20).

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

platformenum ·opcional
Plataforma social: twitter, instagram, linkedin, threads o tiktok.
windowDays7 | 30 | 90 ·opcional · default 30
Ventana de consulta en días: 7, 30 o 90 (por defecto 30).

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

platformenum ·obligatorio
Plataforma social: twitter, instagram, linkedin, threads o tiktok.
contentstring ·obligatorio
Cuerpo de la publicación (1-2200 caracteres).
channelNamestring ·opcional
Qué cuenta conectada, cuando la plataforma tiene más de una.
providerIdstring ·opcional
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.
mediaUrlsarray<string> ·opcional
Hasta 10 URLs de imágenes o vídeos.
clientRequestIdstring ·opcional
Clave de idempotencia opcional. La misma clave en 5 minutos devuelve el resultado en caché.

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 Plan de pago

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

Argumentos

postIdstring ·obligatorio
ID de publicación de PostNext obtenido de una llamada de listado.
contentstring ·opcional
Cuerpo de la publicación (1-2200 caracteres).
mediaUrlsarray<string> ·opcional
Hasta 10 URLs de imágenes o vídeos.
clientRequestIdstring ·opcional
Clave de idempotencia opcional. La misma clave en 5 minutos devuelve el resultado en caché.

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

platformenum ·obligatorio
Plataforma social: twitter, instagram, linkedin, threads o tiktok.

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

postIdstring ·obligatorio
ID de publicación de PostNext obtenido de una llamada de listado.
scheduledAtstring (ISO 8601) ·obligatorio
Timestamp ISO 8601; no puede estar más de 5 minutos en el pasado.

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

postIdstring ·obligatorio
ID de publicación de PostNext obtenido de una llamada de listado.

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

postIdstring ·obligatorio
ID de publicación de PostNext obtenido de una llamada de listado.

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

postIdstring ·obligatorio
ID de publicación de PostNext obtenido de una llamada de listado.

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

querystring ·obligatorio
Subcadena a buscar (3-200 caracteres; los metacaracteres regex se escapan).
statusenum ·opcional
Opcional: DRAFT | SCHEDULED | PUBLISHED | FAILED | CANCELLED.
platformenum ·opcional
Plataforma social: twitter, instagram, linkedin, threads o tiktok.
limitnumber ·opcional · default 20
Número máximo de resultados a devolver (1-100, por defecto 20).

Devuelve

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

teamIdstring ·obligatorio
teamId destino de list_teams. La membresía se revalida en el servidor.

Devuelve

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 9728
  • GET /.well-known/oauth-authorization-server — RFC 8414
  • GET /oauth/.well-known/openid-configuration — OIDC
  • POST /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.