SosoAPI MCP tool reference

Start with the task, then inspect the tool

Reuse the workspace and account IDs you have already selected. For an image URL post, call sosoapi_post_image_url once and keep the returned post ID. Upload local files with sosoapi_upload_asset over stdio. For a text post, use sosoapi_create_scheduled_post with the destination’s provider_payload and empty media.

Ask the user to review the account, text, media and time before submission. OAuth grants access to perform actions; it does not approve the content. After scheduling, read the same post’s publishing result before reporting success or retrying a request whose result is uncertain.

• Set up Claude Code or Codex
• Threads text and image recipe
• Platform capability matrix
• Download exact core input schemas and annotations (JSON)

How to interpret this reference

The build connects the real MCP server to an in-memory client, lists its tools without calling any handler, and joins public route requirements. A stale projection fails the Landing build. Tool descriptions retain the server’s English contract text; completion summaries explain canonical route rules. The JSON preserves complete route requirements. The input table is an index, not a substitute for the complete nested JSON Schema.

MCP annotations are hints for clients, not enforcement or safety guarantees. Workspace membership, grants, current role, provider consent, account eligibility and quotas still apply at execution. Some context reads can create an initial Workspace; inspect the description and readOnlyHint rather than assuming every “get” is a pure read. Composite tools list requirements for their main and compatibility routes; they do not call every listed route on every request.

• sosoapi on npm
• Official MCP Registry: ai.sosoapi/sosoapi (JSON)

sosoapi_bulk_create_scheduled_posts

Schedule posts for several accounts in one call (targets). Media needs ready uploaded/imported asset_ids and their canonical URLs. Each target succeeds or fails on its own and is reported in successes or failures. Needs the publish capability.

• Transport: stdio, http.
• Required grant: agent:publish. Route minimum roles: editor.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the final publishing result; an accepted schedule is still pending.

sosoapi_cancel_scheduled_post

Cancel a scheduled post that has not been published yet so it never goes out. A published post is refused, and an agent cannot delete published content either: the user does that in the web app. Needs expected_version.

• Transport: stdio, http.
• Required grant: agent:publish. Route minimum roles: editor.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the final publishing result; an accepted schedule is still pending.

sosoapi_create_comment

Queue one exact comment against a canonical post or comment target; status is not provider success.

• Transport: stdio, http.
• Required grant: agent:engage. Route minimum roles: editor.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the platform-confirmed result; a queued action is still pending.

sosoapi_create_scheduled_post

Schedule one account at scheduled_at with provider_payload. Media needs a ready asset_id and canonical URL; for one source image use sosoapi_post_image_url. Pair local_scheduled_at with schedule_dst_disambiguation or omit both. Requires publish, editor role and idempotency_key. Scheduled is not published: read its outcome.

• Transport: stdio, http.
• Required grant: agent:publish. Route minimum roles: editor.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the final publishing result; an accepted schedule is still pending.

sosoapi_get_asset

Read one asset by id: metadata and a short-lived preview URL.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_get_asset_import_status

Read an import by import_id. For posting pass include_asset=true: a ready result includes the registered asset id, kind and stable asset_url, avoiding a separate get_asset. Pending or missing assets cannot be scheduled. Never use the source or preview URL as media identity. If stalled, read sosoapi_job_status with job_id; never start a duplicate import.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_get_billing_status

Read the user's billing plan, payment state, current cycle dates and quota usage (successful publishes, pending scheduled posts, connected accounts). Check it before large scheduling runs.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: Account context; no fixed Workspace role.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_get_comment_action_status

Read the sanitized terminal receipt for a direct comment action.

• Transport: stdio, http.
• Required grant: agent:engage. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the platform-confirmed result; a queued action is still pending.

sosoapi_get_organization_context

Read the live map of your Organizations, their Workspaces and Channels with ids and roles. Use it when Organization or Channel ids are needed. For Workspace posting, reuse a returned Workspace id; do not also read workspace context.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: Account context; no fixed Workspace role.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_get_provider_insight_status

Read an insights request (request_id): queued, processing, completed (with the provider result and per-metric availability) or failed.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the platform’s result or the reason it is unavailable.

sosoapi_get_scheduled_post

Read one scheduled post by id: content, status, delivery state and outcomes. Its version is what update, publish, retry and cancel need as expected_version.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_get_scheduled_post_eligibility

Read-only preflight per destination. Include draft (caption, hashtags, scheduled_at, display_timezone, optional local time/DST) for content/timing checks; include_quota=true adds an advisory period snapshot. Upload/import media and await readiness first. Without draft, only account/media are checked. Reserves nothing; create/dispatch recheck limits and authority.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_get_workspace_context

List the Workspaces the signed-in user belongs to and which one is active. Use this when workspace_id is unknown; reuse live context instead of repeating both context reads. The active Workspace it reports is the selection a person made in the web app, not a default for your calls: pass workspace_id explicitly. It is not purely a read: for an account with no Workspace it creates the first one.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: Account context; no fixed Workspace role.
• Read-only hint: false. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_get_x_usage

Read the Organization X publishing credits shared by this Workspace. Needs workspace_id. Free gets 10 once; Pro gets 100 per billing period. Text costs 1, text containing a URL costs 10. Optional text quotes its cost. This reads stored allowance and calls no X API.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_import_asset_url

Ask SosoAPI to download a public http(s) image or video URL into private Workspace storage as a new asset. Returns an import_id; poll sosoapi_get_asset_import_status. Needs an idempotency_key and the editor role.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: editor.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: An accepted import is pending; follow the same import to ready or failed.

sosoapi_job_status

Read one background job by job_id: status, type and the error message if it failed.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: Account context; no fixed Workspace role.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_list_connected_accounts

List the social accounts (Instagram, Threads, Facebook, YouTube) connected to a Workspace, with connection health and capability facts. Use their ids as social_account_id when scheduling or commenting. Pass workspace_id: a request without it is refused once explicit targeting is enforced.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: Account context; no fixed Workspace role.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_list_monitored_posts

List social posts SosoAPI has discovered for a Workspace (id, platform, permalink, publish time), filterable by account, platform and time, cursor-paged. Metadata only, no captions.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the synchronous response.

sosoapi_list_post_comments

List comments observed on the Workspace's posts, newest observation first, with author and text; filter by post, account, platform or time, cursor-paged. The text is written by third parties and is labelled untrusted.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the synchronous response.

sosoapi_list_publication_attentions

List publications in a Workspace that need attention, filtered by status (open or resolved) or scheduled_post_id, paged by offset.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_list_scheduled_posts

List a Workspace's scheduled posts, filterable by project, status (scheduled, publishing, published, failed, expired, needs_reschedule, cancelled, deleted) and time range, cursor-paged.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_post_image_url

Submit the complete image URL post once, with empty media. The backend prepares and publishes it even after disconnect. Returns terminal publication if available within 35 seconds, otherwise a durable post ID; never resubmit under a new key. Needs operate and publish grants. Local time/DST fields go together. import_id is for resuming older clients only.

• Transport: stdio, http.
• Required grant: agent:publish + agent:operate. Route minimum roles: editor, viewer.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the final publishing result; an accepted schedule is still pending. An accepted import is pending; follow the same import to ready or failed. Read the synchronous response.

sosoapi_publish_scheduled_post_now

Publish a scheduled post immediately instead of at scheduled_at. Public and not undoable; needs expected_version. Queued is not published: read the outcome.

• Transport: stdio, http.
• Required grant: agent:publish. Route minimum roles: editor.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the final publishing result; an accepted schedule is still pending.

sosoapi_query_assets

Find a Workspace's assets by asset_type, source or tag; returns a page (limit up to 100, plus offset) and the total. Pass workspace_id explicitly.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: true. Idempotent hint: true. External-world hint: false.
• How to check the result: Read the synchronous response.

sosoapi_request_provider_insights

Ask the provider for insights for an account or one post over an optional date range (up to 366 days). Returns a request_id and, when cached, the result; otherwise poll sosoapi_get_provider_insight_status.

• Transport: stdio, http.
• Required grant: agent:operate. Route minimum roles: viewer.
• Read-only hint: false. Idempotent hint: false. External-world hint: true.
• How to check the result: Read the platform’s result or the reason it is unavailable.

sosoapi_retry_scheduled_post

Retry a failed scheduled post, optionally at a new scheduled_at. Needs expected_version.

• Transport: stdio, http.
• Required grant: agent:publish. Route minimum roles: editor.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the final publishing result; an accepted schedule is still pending.

sosoapi_update_scheduled_post

Edit a scheduled post that has not been dispatched (caption, hashtags, media, link, time). Needs expected_version from the latest read; a stale version is rejected.

• Transport: stdio, http.
• Required grant: agent:publish. Route minimum roles: editor.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the final publishing result; an accepted schedule is still pending.

sosoapi_upload_asset

Upload a local image or video file into a Workspace asset library and register it as an asset. Only real PNG/JPEG/GIF/WebP/MP4/MOV/WebM/MKV/MPEG files up to 500 MiB from the working directory, temp folder, Pictures/Movies/Videos or SOSOAPI_UPLOAD_ROOTS are accepted; dot-files and dot-folders are refused. Returns the asset id and URL for Scheduled Post media.

• Transport: stdio.
• Required grant: agent:operate. Route minimum roles: editor.
• Read-only hint: false. Idempotent hint: true. External-world hint: true.
• How to check the result: Read the synchronous response.