Early Access

Documentación de la API y MCP

Qué expone el servidor MCP de Pushrank y cómo llamarlo manualmente a través de la API.

Herramientas expuestas

El servidor MCP de Pushrank expone 49 herramientas. Todas las respuestas se limitan a los proyectos de su organización; las 26 acciones de escritura se indican a continuación. Solo se aceptan los parámetros enumerados: cualquier parámetro no declarado se rechaza con un error que indica la clave, nunca se ignora en silencio.

whoami

Muestra el usuario autenticado, las organizaciones accesibles, los permisos concedidos, los saldos de créditos y enlaces útiles de Pushrank.

Parámetros: Ninguno. Solo lectura, sin permisos adicionales.

list_projects

Lista los proyectos de Pushrank accesibles para el usuario autenticado.

Parámetros: limit (1–50, 25 por defecto).

get_project_overview

Resumen compacto de un proyecto: tráfico, resumen del digest y recuento de estados.

Parámetros: projectId.

get_seo_forecast

Previsión SEO de un proyecto, en solo lectura: la estimación de Pushrank (control deslizante en su posición por defecto) con su curva, M6, M12, total acumulado, coste, umbral, cobertura, referencia de consultor, hipótesis y procedencia, o el motivo por el que no está disponible. Mismo nivel de detalle que la aplicación para la cuenta. Una hipótesis, no una garantía.

Parámetros: projectId.

list_seo_opportunities

Recupera automáticamente la lista completa de acciones SEO que coinciden con su solicitud, activas por defecto, y guía al asistente para presentarlas en una tabla. El alcance y los estados del ciclo de vida coinciden con la pantalla Acciones; la respuesta también explica las acciones ocultas en esa pantalla.

Parámetros: projectId; opcionales: status (active por defecto | todo | in_progress | done | verified | still_present | ignored | all), type, severity, priority, source, query, pageUrl, priorityMin. pagination=all por defecto; pagination=page activa el acceso técnico página por página con page (1 por defecto) y pageSize (10 por defecto, máximo 25).

update_seo_opportunity_statusEscritura · mcp:actions:write

Actualiza el estado de una o varias oportunidades SEO (hasta 50 por llamada) y devuelve un resultado por oportunidad: aplicado, ya en ese estado o rechazado con su motivo. Requiere el scope mcp:actions:write.

Parámetros: projectId, status; opportunityId para una oportunidad, u opportunityIds (de 1 a 50) para un lote.

get_gsc_digest

Devuelve el último digest de GSC completado y el estado del último intento; no genera un nuevo digest.

Parámetros: projectId; kind (dashboard_digest | weekly_gsc | monthly_gsc, dashboard_digest por defecto).

get_gsc_snapshot

Lee únicamente las instantáneas conservadas de Google Search Console; nunca consulta GSC en directo.

Parámetros: projectId, dimension (date | page | query | query_page | page_date); opcionales: period, compareTo (misma duración), pageUrl, offset, limit (máx. 50).

list_articles

Lista los artículos con puntuaciones, estado de calidad y metadatos de publicación, sin el contenido completo.

Parámetros: projectId; opcionales: status, search, limit (máx. 25).

get_article

Devuelve un artículo completo: contenido, meta, informes de calidad, registros de publicación, palabras clave vinculadas, oportunidades y ejecuciones de agentes.

Parámetros: projectId, articleId.

get_article_generation_readiness

Comprueba la cuota, la completitud del brief, la canibalización y las alertas de SERP antes de la generación, sin crear nada.

Parámetros: projectId, keyword, intent, articleType; opcionales: niche, languageCode.

generate_articleEscritura · mcp:articles:generate

Inicia el flujo normal de generación de artículos con cuotas y controles de seguridad. Requiere mcp:articles:generate.

Parámetros: projectId, keyword, intent, idempotencyKey (UUID); opcionales: articleType, niche, languageCode, brief, opportunityId, acknowledgeWarnings.

get_workflow_status

Consulta el progreso de la generación de un artículo o de una publicación en el CMS.

Parámetros: projectId y exactamente uno de requestId o articleId; opcional: publicationJobId.

get_article_publication_readiness

Comprueba el contenido del artículo, la calidad, la conexión con el CMS, las capacidades y la procedencia antes de publicar.

Parámetros: projectId, articleId.

publish_article_to_cmsEscritura · mcp:articles:publish

Publica o actualiza realmente el artículo en el CMS conectado. Requiere mcp:articles:publish.

Parámetros: projectId, articleId, idempotencyKey (UUID), confirmed=true; opcional: acknowledgeQualityOverride.

list_content_plan

Devuelve el plan editorial actual y el estado de cada tema planificado.

Parámetros: projectId.

generate_article_from_plan_itemEscritura · mcp:articles:generate

Inicia el flujo normal de generación a partir de un elemento del plan tras su confirmación. Requiere mcp:articles:generate.

Parámetros: projectId, itemId, confirmed=true; opcional: acknowledgeWarnings.

edit_articleEscritura · mcp:articles:write

Previsualiza y después aplica cambios en el artículo con control optimista de versiones. Aplicar requiere mcp:articles:write.

Parámetros: projectId, articleId, mode, expectedUpdatedAt, changes (title, slug, content, metaDescription, faqData, ctaData, robotsConfig{index, follow, noSnippet, noArchive}, featuredImageAlt); confirmed=true para aplicar. Un ctaData con html "" o blocks [] queda sin CTA, incluso con una URL; un CTA sin URL válida no se muestra.

get_article_performance

Lee el rendimiento de GSC conservado para la página publicada sin consultar Google en directo.

Parámetros: projectId, articleId.

add_keywordsEscritura · mcp:keywords:write

Previsualiza y después añade hasta 100 palabras clave a la estrategia. Las nuevas palabras clave se enriquecen (volumen, dificultad, SERP, intención) como al añadirlas desde el panel, sin coste de créditos y con un plan activo. Una palabra clave eliminada anteriormente se restablece. Aplicar requiere mcp:keywords:write.

Parámetros: projectId, mode, terms[], locale, intent; confirmed=true e idempotencyKey para aplicar.

update_keywordEscritura · mcp:keywords:write

Previsualiza y después sobrescribe la intención, el estado o la puntuación de prioridad de una palabra clave. Aplicar requiere mcp:keywords:write.

Parámetros: projectId, mode, keywordId, changes (intent, status, priorityScore); confirmed=true e idempotencyKey para aplicar.

set_keyword_statusesEscritura · mcp:keywords:write

Previsualiza y después asigna un mismo estado a hasta 100 palabras clave. Aplicar requiere mcp:keywords:write.

Parámetros: projectId, mode, keywordIds[], status; confirmed=true e idempotencyKey para aplicar.

get_page_reanalysis_readiness

Comprueba la URL, la página conocida, el trabajo duplicado y los créditos antes de volver a ejecutar el análisis.

Parámetros: projectId, pageUrl.

reanalyze_pageEscritura · mcp:analysis:run

Vuelve a ejecutar el análisis SEO normal de una página, con consumo de créditos. Requiere mcp:analysis:run.

Parámetros: projectId, pageUrl, idempotencyKey, confirmed=true.

get_editorial_context

Lee el contexto editorial estructurado sin exponer los documentos RAG internos.

Parámetros: projectId.

edit_editorial_contextEscritura · mcp:editorial:write

Previsualiza y después aplica el contexto editorial estructurado con control de versiones. Aplicar requiere mcp:editorial:write.

Parámetros: projectId, mode, expectedUpdatedAt, changes (brandName, primaryOffer, audience, benefits, positioning, tone, proofs[]{claim, sourceUrl, excerpt}); confirmed=true para aplicar.

get_business_profile

Lee el perfil de negocio completo: cada dato con su estado, procedencia y decisión, el grado de preparación, los campos esenciales que faltan y el modo heredado.

Parámetros: projectId.

declare_business_factEscritura · mcp:editorial:write

Previsualiza y después declara un dato en el perfil de negocio (oferta, público, mercado, objetivo, regla, restricción, estacionalidad o término). Si la dirección ya tiene un valor, este se sustituye. Aplicar requiere mcp:editorial:write.

Parámetros: projectId, mode, expectedRevision, idempotencyKey, address, value; confirmed=true para aplicar.

replace_business_factEscritura · mcp:editorial:write

Previsualiza y después sobrescribe el valor de un dato de negocio. Aplicar requiere mcp:editorial:write.

Parámetros: projectId, mode, expectedRevision, idempotencyKey, factId, value; confirmed=true para aplicar.

confirm_business_factEscritura · mcp:editorial:write

Previsualiza y después confirma un dato de negocio propuesto. Aplicar requiere mcp:editorial:write.

Parámetros: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true para aplicar.

reject_business_factEscritura · mcp:editorial:write

Previsualice y luego rechace un dato de negocio propuesto o confirmado; podrá restaurarlo más tarde. Para aplicar se requiere mcp:editorial:write.

Parámetros: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true para aplicar.

withdraw_business_factEscritura · mcp:editorial:write

Previsualice y luego elimine definitivamente un dato de negocio; no podrá restaurarse. Para aplicar se requiere mcp:editorial:write.

Parámetros: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true para aplicar.

restore_business_factEscritura · mcp:editorial:write

Previsualice y luego devuelva un dato de negocio rechazado al estado propuesto. Para aplicar se requiere mcp:editorial:write.

Parámetros: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true para aplicar.

reorder_business_offersEscritura · mcp:editorial:write

Previsualice y luego sustituya el orden de las ofertas. Para aplicar se requiere mcp:editorial:write.

Parámetros: projectId, mode, expectedRevision, idempotencyKey, offerIds[]; confirmed=true para aplicar.

adopt_business_profileEscritura · mcp:editorial:write

Solo en modo heredado: previsualice y luego confirme el perfil recuperado de los datos existentes, rechazando los datos erróneos y declarando los campos esenciales que faltan en el mismo cambio. No se puede deshacer. Para aplicar se requiere mcp:editorial:write.

Parámetros: projectId, mode, expectedRevision, idempotencyKey, rejectFactIds[], missingFacts[]{address, value}; confirmed=true para aplicar.

retry_project_contextEscritura · mcp:editorial:write

Vuelva a lanzar la reconstrucción del contexto del proyecto tras un fallo (projectContext.retry = available en get_article_generation_readiness), como el botón de los ajustes. Previsualice el estado y luego vuelva a ponerla en cola; una llamada repetida devuelve la reconstrucción ya en cola; tras un nuevo fallo, cada aplicación es un nuevo reintento. Para aplicar se requiere mcp:editorial:write.

Parámetros: projectId, mode; confirmed=true para aplicar.

get_cms_config

Consulte el tipo de CMS, el estado de la conexión, la fecha de la última prueba y los ajustes no secretos. Los secretos nunca se devuelven; solo se indica si cada uno está guardado.

Parámetros: projectId.

configure_cmsEscritura · mcp:integrations:write

Previsualice y luego guarde y pruebe los ajustes no secretos de una conexión existente de WordPress, Webflow, Wix, Framer (si está habilitado) o webhook personalizado. Las credenciales solo se introducen en el panel de PushRank y no se modifican. Shopify se gestiona en el panel. Para aplicar se requieren mcp:integrations:write y el rol de propietario.

Parámetros: projectId, mode, cmsType; según el tipo: wpUrl, wpUsername | webflowCollectionId | wixSiteId, wixMemberId | framerProjectId, framerCollectionId, framerFieldMapping (Framer, si está habilitado) | webhookUrl; confirmed=true e idempotencyKey para aplicar.

get_publishing_schedule

Consulte la planificación de artículos definida en la tarjeta Temas: activada/desactivada, días, hora, zona horaria y Publicar sin revisión, el próximo artículo planificado y lo que permite la cuota de artículos hasta su renovación.

Parámetros: projectId.

update_publishing_scheduleEscritura · mcp:articles:generate, mcp:articles:publish

Previsualice y luego aplique un cambio en la planificación de artículos, con las mismas reglas que la tarjeta Temas. Para aplicar se requiere mcp:articles:generate para cambiar activación, días, hora o zona horaria, y mcp:articles:publish para cambiar Publicar sin revisión.

Parámetros: projectId, mode; opcionales enabled, publishDays (de 0 a 7 días entre mon…sun), publishHour (0–23), timezone (Europe/Paris, Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo), autoPublish; confirmed=true e idempotencyKey para aplicar.

update_article_statusEscritura · mcp:actions:write

Registre el estado de publicación guardado de un artículo y la procedencia MCP. Requiere el scope mcp:actions:write.

Parámetros: projectId, articleId, status (draft | published); opcionales: cmsUrl (solo HTTPS), publishedAt (ISO 8601, solo published; por defecto, ahora). La programación no está disponible porque esta herramienta no tiene marca de tiempo de programación.

schedule_article_publicationEscritura · mcp:actions:write

Programe una publicación futura de un artículo con el control de calidad existente y la protección contra concurrencia. Requiere el scope mcp:actions:write.

Parámetros: projectId, articleId, scheduledAt (marca de tiempo ISO 8601 futura con desfase explícito).

cancel_article_publication_scheduleEscritura · mcp:actions:write

Cancele una publicación de artículo programada pendiente. Se rechaza en cuanto el proceso de publicación la ha tomado. Requiere el scope mcp:actions:write.

Parámetros: projectId, articleId.

list_keywords

Liste las palabras clave enriquecidas con métricas, estado, prioridad, cobertura de artículos e intención canónica.

Parámetros: projectId; opcionales: intent, source, status, search, limit (máx. 25), offset (paginar con pagination.nextOffset).

get_keyword_metrics

Devuelve las métricas ya guardadas de hasta 20 términos; nunca llama a un proveedor ni lanza una actualización.

Parámetros: projectId, terms (1–20); opcionales: locale (por defecto fr), locationCode (por defecto 2250).

get_onboarding_checklist

Muestre los cinco pasos de inicio de un proyecto, lo que queda por hacer, el enlace al panel de cada paso y el estado del backlink de bienvenida. Los clientes compatibles con MCP Apps lo muestran como una lista de comprobación interactiva.

Parámetros: projectId.

claim_welcome_giftEscritura · mcp:backlinks:write

Previsualice y luego solicite el backlink ofrecido al completar los cinco pasos: una página del sitio del proyecto y su texto ancla. Solo para el propietario, con una prueba o un plan activo; uno por organización. Durante la prueba, el backlink solo queda reservado: se encarga al terminar la prueba, con el primer mes de pago. Para aplicar se requiere mcp:backlinks:write.

Parámetros: projectId, mode, targetUrl, anchorText; confirmed=true para aplicar.

get_ai_visibility

Lee la visibilidad en IA de un proyecto: prompts seguidos, puntuación, resultados por prompt y por motor de IA (citado, mencionado, posición, extracto), periodos de medición y, opcionalmente, la comparación con la competencia. Nunca devuelve el texto completo de las respuestas ni lanza una medición.

Parámetros: projectId; opcionales: collectionId, prompt, provider, offset, limit (1–25, 15 por defecto), includeCompetitors.

manage_ai_visibility_promptsEscritura · mcp:ai-visibility:write

Previsualiza y luego aplica añadir, quitar o reformular prompts seguidos. Un prompt reformulado empieza sin historial. Nunca lanza una medición: los nuevos prompts se miden en la siguiente medición. Aplicar requiere mcp:ai-visibility:write.

Parámetros: projectId, mode, operation (add con prompts, remove con prompts o rename con from y to); confirmed=true para aplicar.

Conexión OAuth

Los clientes MCP como Claude o ChatGPT se conectan mediante OAuth: deles el endpoint y descubrirán el resto en los metadatos siguientes.

Metadatos del recursohttps://ai.pushrank.io/.well-known/oauth-protected-resource/mcp
Servidor de autorizaciónhttps://app.pushrank.io/.well-known/oauth-authorization-server
  1. Descubrimiento — una llamada sin autenticar al endpoint devuelve 401 con una cabecera WWW-Authenticate que apunta a los metadatos del recurso, que indican el servidor de autorización y los scopes admitidos.
  2. Registro — el cliente se registra mediante registro dinámico (registration_endpoint) como cliente público, sin secreto.
  3. Autorización — flujo authorization code con PKCE (S256) y el parámetro resource igual al endpoint MCP; el usuario inicia sesión en Pushrank y acepta los scopes solicitados.
  4. Tokens — el token_endpoint devuelve un token de acceso de 1 h y un token de actualización de 30 días cuando se solicita offline_access. Envíe el token de acceso como Authorization: Bearer.

Uso manual de la API

Para un script o un cliente sin OAuth, llame al endpoint JSON-RPC 2.0 con un token bearer creado desde la pestaña "API / manual".

Endpointhttps://ai.pushrank.io/mcp

Cabeceras obligatorias

  • Authorization: Bearer <token> — obligatoria en cada solicitud.
  • Content-Type: application/json.
  • Accept: application/json, text/event-stream.
  • mcp-session-id — se devuelve en las cabeceras de la respuesta de initialize; repítala en cada llamada posterior.
  • mcp-protocol-version: 2025-06-18 en las llamadas posteriores a initialize.

Secuencia de llamadas

1. initialize — abre una sesión. Lea la cabecera de respuesta mcp-session-id (curl -i).

terminal
curl -i -X POST "https://ai.pushrank.io/mcp" \
  -H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"pushrank-manual-client","version":"1.0"}}}'

2. tools/list — lista las herramientas disponibles y sus esquemas de entrada.

terminal
curl -X POST "https://ai.pushrank.io/mcp" \
  -H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id>" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

3. tools/call — ejecuta una herramienta con sus argumentos.

terminal
curl -X POST "https://ai.pushrank.io/mcp" \
  -H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id>" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_projects","arguments":{"limit":10}}}'
El servidor tiene estado: sin una cabecera mcp-session-id válida, cualquier llamada posterior a initialize devuelve "Session not found" (404).

Scopes, límites y revocación

Los tokens MCP son exclusivos e independientes de su sesión.

Token manual

Un token manual incluye por defecto los scopes mcp:projects:read y mcp:actions:read. Nunca caduca y puede revocarse en cualquier momento.

Acciones de escritura

Las actualizaciones de estado y de programación requieren mcp:actions:write. La generación usa mcp:articles:generate, la publicación mcp:articles:publish, la edición de artículos mcp:articles:write, los cambios de palabras clave mcp:keywords:write, el reanálisis mcp:analysis:run, el contexto editorial mcp:editorial:write, los cambios de conexión al CMS mcp:integrations:write, la solicitud del backlink de bienvenida mcp:backlinks:write y los prompts seguidos de Visibilidad en IA mcp:ai-visibility:write. Los cambios en la planificación de artículos usan mcp:articles:generate, y Publicar sin revisión mcp:articles:publish. Estos scopes específicos se conceden mediante OAuth o se marcan en una clave manual, al crearla o más tarde. Un token sin el scope necesario recibe insufficientScope.

Duración en OAuth

Para los clientes OAuth (Claude, ChatGPT…), el token de acceso dura 1 h y el token de actualización 30 días.

Revocación

Revoque un token manual desde la pestaña "API / manual". La revocación es inmediata y no afecta a su sesión; el acceso OAuth se revoca desde el cliente conectado.

Alcance por organización

El servidor limita cada respuesta a los proyectos de las organizaciones a las que usted pertenece.