Referencia de herramientas MCP de SosoAPI

Empieza por la tarea y examina la herramienta

Reutiliza los IDs de espacio y cuenta que ya elegiste. Para una publicación de imagen por URL, llama una vez a sosoapi_post_image_url y conserva el ID devuelto. Carga archivos locales con sosoapi_upload_asset por stdio. Para texto, usa sosoapi_create_scheduled_post con el provider_payload del destino y media vacío.

Pide al usuario revisar cuenta, texto, archivos multimedia y hora antes de enviar. OAuth concede acceso para realizar acciones; no aprueba el contenido. Tras programar, consulta el resultado de la misma publicación antes de informar de éxito o reintentar una solicitud de resultado incierto.

• Configura Claude Code o Codex
• Guía de texto e imágenes para Threads
• Matriz de capacidades por plataforma
• Descargar esquemas de entrada y anotaciones exactos de core (JSON)

Cómo interpretar esta referencia

La compilación conecta el servidor MCP real a un cliente en memoria, lista sus herramientas sin llamar a ningún controlador y combina los requisitos de rutas públicas. Una proyección desactualizada hace fallar la compilación de Landing. Las descripciones de herramientas conservan el texto contractual en inglés del servidor; los resúmenes de finalización explican las reglas de rutas canónicas. El JSON conserva los requisitos completos de las rutas. La tabla de entradas es un índice, no sustituye al JSON Schema anidado completo.

Las anotaciones MCP son indicaciones para clientes, no controles ni garantías de seguridad. La pertenencia al espacio, permisos, rol actual, consentimiento del proveedor, elegibilidad de cuenta y cuotas siguen aplicándose al ejecutar. Algunas lecturas de contexto pueden crear un espacio inicial; consulta la descripción y readOnlyHint en vez de suponer que cada «get» es lectura pura. Las herramientas compuestas enumeran requisitos de sus rutas principal y de compatibilidad; no llaman a todas las rutas enumeradas en cada solicitud.

• sosoapi en npm
• Registro oficial MCP: ai.sosoapi/sosoapi (JSON)

sosoapi_bulk_create_scheduled_posts

Programa publicaciones para varias cuentas en una llamada (targets). Los archivos multimedia requieren asset_ids cargados o importados y listos, con sus URL canónicas. Cada destino tiene éxito o falla de forma independiente y aparece en successes o failures. Requiere la capacidad publish.

• Transporte: stdio, http.
• Permiso requerido: agent:publish. Roles mínimos de la ruta: editor.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado final de publicación; una programación aceptada sigue pendiente.

sosoapi_cancel_scheduled_post

Cancela una publicación programada que aún no se ha publicado para evitar su envío. Se rechazan las publicaciones ya publicadas y un agente tampoco puede eliminar contenido publicado: el usuario debe hacerlo en la aplicación web. Requiere expected_version.

• Transporte: stdio, http.
• Permiso requerido: agent:publish. Roles mínimos de la ruta: editor.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado final de publicación; una programación aceptada sigue pendiente.

sosoapi_create_comment

Pone en cola un comentario exacto dirigido a una publicación o un comentario canónicos; el estado no implica éxito en el proveedor.

• Transporte: stdio, http.
• Permiso requerido: agent:engage. Roles mínimos de la ruta: editor.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado confirmado por la plataforma; una acción en cola sigue pendiente.

sosoapi_create_scheduled_post

Programa una cuenta en scheduled_at con provider_payload. Los archivos multimedia requieren un asset_id listo y una URL canónica; para una imagen de origen usa sosoapi_post_image_url. Incluye juntos local_scheduled_at y schedule_dst_disambiguation, u omite ambos. Requiere publish, el rol editor e idempotency_key. Programado no significa publicado: consulta el resultado.

• Transporte: stdio, http.
• Permiso requerido: agent:publish. Roles mínimos de la ruta: editor.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado final de publicación; una programación aceptada sigue pendiente.

sosoapi_get_asset

Consulta un recurso por id: metadatos y una URL de vista previa de corta duración.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_get_asset_import_status

Consulta una importación por import_id. Para publicar, proporciona include_asset=true: un resultado ready incluye el id del recurso registrado, su tipo y una asset_url estable, evitando un get_asset adicional. No se pueden programar recursos pendientes o ausentes. Nunca uses la URL de origen o vista previa como identidad del archivo multimedia. Si se bloquea, consulta sosoapi_job_status con job_id; nunca inicies una importación duplicada.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_get_billing_status

Consulta el plan de facturación del usuario, el estado del pago, las fechas del ciclo actual y el uso de cuotas (publicaciones exitosas, publicaciones programadas pendientes, cuentas conectadas). Compruébalo antes de programar grandes lotes.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: contexto de cuenta; sin rol fijo de espacio de trabajo.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_get_comment_action_status

Consulta el comprobante definitivo depurado de una acción directa de comentario.

• Transporte: stdio, http.
• Permiso requerido: agent:engage. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado confirmado por la plataforma; una acción en cola sigue pendiente.

sosoapi_get_organization_context

Consulta el mapa actual de tus organizaciones, sus espacios de trabajo y canales, con sus ids y roles. Úsalo cuando necesites ids de organización o canal. Para publicar en un espacio de trabajo, reutiliza un id de espacio de trabajo devuelto; no leas además su contexto.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: contexto de cuenta; sin rol fijo de espacio de trabajo.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_get_provider_insight_status

Consulta una solicitud de estadísticas (request_id): queued, processing, completed (con el resultado del proveedor y la disponibilidad por métrica) o failed.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado de la plataforma o el motivo por el que no está disponible.

sosoapi_get_scheduled_post

Consulta una publicación programada por id: contenido, estado, estado de entrega y resultados. Su versión es el valor expected_version que necesitan las operaciones de actualización, publicación, reintento y cancelación.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_get_scheduled_post_eligibility

Comprobación previa de solo lectura por destino. Incluye draft (caption, hashtags, scheduled_at, display_timezone, hora local/DST opcional) para comprobar contenido y horarios; include_quota=true añade una instantánea orientativa del período. Primero carga o importa los archivos multimedia y espera a que estén listos. Sin draft, solo se comprueban la cuenta y los archivos. No reserva nada; la creación y el despacho vuelven a comprobar límites y autoridad.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_get_workspace_context

Lista los espacios de trabajo a los que pertenece el usuario que ha iniciado sesión e indica cuál está activo. Úsalo si no conoces workspace_id; reutiliza el contexto actual en vez de repetir ambas lecturas de contexto. El espacio de trabajo activo que indica es el elegido por una persona en la aplicación web, no un valor predeterminado para tus llamadas: proporciona workspace_id explícitamente. No es solo una lectura: para una cuenta sin espacio de trabajo, crea el primero.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: contexto de cuenta; sin rol fijo de espacio de trabajo.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_get_x_usage

Consulta los créditos de publicación en X de la organización compartidos por este espacio de trabajo. Requiere workspace_id. Free recibe 10 una sola vez; Pro recibe 100 por período de facturación. Un texto cuesta 1; un texto con URL cuesta 10. El texto opcional permite calcular su costo. Solo lee la asignación almacenada, sin llamar a la API de X.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_import_asset_url

Solicita a SosoAPI descargar una imagen o un video desde una URL http(s) pública al almacenamiento privado del espacio de trabajo como recurso nuevo. Devuelve un import_id; consulta sosoapi_get_asset_import_status. Requiere un idempotency_key y el rol editor.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: editor.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Una importación aceptada está pendiente; sigue esa misma importación hasta ready o failed.

sosoapi_job_status

Consulta una tarea en segundo plano por job_id: estado, tipo y mensaje de error si falló.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: contexto de cuenta; sin rol fijo de espacio de trabajo.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_list_connected_accounts

Lista las cuentas sociales (Instagram, Threads, Facebook, YouTube) conectadas a un espacio de trabajo, con datos del estado de conexión y las capacidades. Usa sus ids como social_account_id al programar o comentar. Proporciona workspace_id: una solicitud sin él se rechaza cuando se exige un destino explícito.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: contexto de cuenta; sin rol fijo de espacio de trabajo.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_list_monitored_posts

Lista las publicaciones sociales que SosoAPI ha detectado en un espacio de trabajo (id, plataforma, enlace permanente, hora de publicación), con filtros por cuenta, plataforma y hora, y paginación por cursor. Solo metadatos, sin textos de publicación.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_list_post_comments

Lista los comentarios observados en las publicaciones del espacio de trabajo, con las observaciones más recientes primero, autor y texto; permite filtrar por publicación, cuenta, plataforma u hora, con paginación por cursor. El texto lo escriben terceros y se etiqueta como no confiable.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_list_publication_attentions

Lista las publicaciones de un espacio de trabajo que requieren atención, filtradas por estado (open o resolved) o scheduled_post_id, con paginación por offset.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_list_scheduled_posts

Lista las publicaciones programadas de un espacio de trabajo, con filtros por proyecto, estado (scheduled, publishing, published, failed, expired, needs_reschedule, cancelled, deleted) e intervalo de tiempo, y paginación por cursor.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_post_image_url

Envía una sola vez la publicación completa con imagen por URL, con media vacío. El backend la prepara y publica incluso tras la desconexión. Devuelve la publicación definitiva si está disponible en 35 segundos; en caso contrario, un ID persistente de publicación. Nunca vuelvas a enviarla con otra clave. Requiere permisos operate y publish. Los campos de hora local/DST van juntos. import_id solo sirve para reanudar clientes antiguos.

• Transporte: stdio, http.
• Permiso requerido: agent:publish + agent:operate. Roles mínimos de la ruta: editor, viewer.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado final de publicación; una programación aceptada sigue pendiente. Una importación aceptada está pendiente; sigue esa misma importación hasta ready o failed. Lee la respuesta síncrona.

sosoapi_publish_scheduled_post_now

Publica una publicación programada de inmediato en lugar de hacerlo en scheduled_at. Es público y no se puede deshacer; requiere expected_version. Estar en cola no significa estar publicado: consulta el resultado.

• Transporte: stdio, http.
• Permiso requerido: agent:publish. Roles mínimos de la ruta: editor.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado final de publicación; una programación aceptada sigue pendiente.

sosoapi_query_assets

Busca recursos de un espacio de trabajo por asset_type, source o tag; devuelve una página (limit hasta 100, más offset) y el total. Proporciona workspace_id explícitamente.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: true. Indicación de idempotencia: true. Indicación de mundo externo: false.
• Cómo comprobar el resultado: Lee la respuesta síncrona.

sosoapi_request_provider_insights

Solicita al proveedor estadísticas de una cuenta o una publicación para un intervalo opcional de fechas (hasta 366 días). Devuelve un request_id y, si está en caché, el resultado; de lo contrario, consulta sosoapi_get_provider_insight_status.

• Transporte: stdio, http.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: viewer.
• Indicación de solo lectura: false. Indicación de idempotencia: false. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado de la plataforma o el motivo por el que no está disponible.

sosoapi_retry_scheduled_post

Reintenta una publicación programada fallida, opcionalmente con un nuevo scheduled_at. Requiere expected_version.

• Transporte: stdio, http.
• Permiso requerido: agent:publish. Roles mínimos de la ruta: editor.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado final de publicación; una programación aceptada sigue pendiente.

sosoapi_update_scheduled_post

Edita una publicación programada que aún no se ha despachado (texto, hashtags, archivos multimedia, enlace, hora). Requiere expected_version de la lectura más reciente; se rechaza una versión desactualizada.

• Transporte: stdio, http.
• Permiso requerido: agent:publish. Roles mínimos de la ruta: editor.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Consulta el resultado final de publicación; una programación aceptada sigue pendiente.

sosoapi_upload_asset

Carga un archivo local de imagen o video en la biblioteca de recursos de un espacio de trabajo y lo registra como recurso. Solo se aceptan archivos reales PNG/JPEG/GIF/WebP/MP4/MOV/WebM/MKV/MPEG de hasta 500 MiB del directorio de trabajo, la carpeta temporal, Pictures/Movies/Videos o SOSOAPI_UPLOAD_ROOTS; se rechazan los archivos y carpetas cuyo nombre empieza por punto. Devuelve el id y la URL del recurso para los archivos multimedia de las publicaciones programadas.

• Transporte: stdio.
• Permiso requerido: agent:operate. Roles mínimos de la ruta: editor.
• Indicación de solo lectura: false. Indicación de idempotencia: true. Indicación de mundo externo: true.
• Cómo comprobar el resultado: Lee la respuesta síncrona.