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.
whoamiMuestra 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_projectsLista los proyectos de Pushrank accesibles para el usuario autenticado.
Parámetros: limit (1–50, 25 por defecto).
get_project_overviewResumen compacto de un proyecto: tráfico, resumen del digest y recuento de estados.
Parámetros: projectId.
get_seo_forecastPrevisió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_opportunitiesRecupera 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:writeActualiza 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_digestDevuelve 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_snapshotLee ú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_articlesLista 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_articleDevuelve 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_readinessComprueba 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:generateInicia 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_statusConsulta 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_readinessComprueba 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:publishPublica 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_planDevuelve el plan editorial actual y el estado de cada tema planificado.
Parámetros: projectId.
generate_article_from_plan_itemEscritura · mcp:articles:generateInicia 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:writePrevisualiza 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_performanceLee el rendimiento de GSC conservado para la página publicada sin consultar Google en directo.
Parámetros: projectId, articleId.
add_keywordsEscritura · mcp:keywords:writePrevisualiza 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:writePrevisualiza 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:writePrevisualiza 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_readinessComprueba 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:runVuelve 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_contextLee el contexto editorial estructurado sin exponer los documentos RAG internos.
Parámetros: projectId.
edit_editorial_contextEscritura · mcp:editorial:writePrevisualiza 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_profileLee 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:writePrevisualiza 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:writePrevisualiza 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:writePrevisualiza 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:writePrevisualice 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:writePrevisualice 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:writePrevisualice 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:writePrevisualice 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:writeSolo 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:writeVuelva 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_configConsulte 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:writePrevisualice 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_scheduleConsulte 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:publishPrevisualice 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:writeRegistre 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:writePrograme 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:writeCancele 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_keywordsListe 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_metricsDevuelve 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_checklistMuestre 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:writePrevisualice 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_visibilityLee 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:writePrevisualiza 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.
https://ai.pushrank.io/.well-known/oauth-protected-resource/mcphttps://app.pushrank.io/.well-known/oauth-authorization-server- 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.
- Registro — el cliente se registra mediante registro dinámico (registration_endpoint) como cliente público, sin secreto.
- 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.
- 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".
https://ai.pushrank.io/mcpCabeceras 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).
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.
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.
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}}}'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.