Docs

MCP quickstart

The MCP server exposes 18 tools over streamable HTTP. Your agent gets the same validation, approvals and audit trail as the REST API.

Requires a key with the mcp scope · about five minutes

Start with a test key. It runs everything (validation, approval, scheduling, the audit chain) against a fake publisher, so nothing reaches X or Instagram until you switch to a live key.

01Create a key§

In the dashboard, open API keys and create a key. New keys carry read, draft and mcp by default: enough for an agent to validate and draft, not to publish. The key is shown once; SMMist stores only its sha256.

export SMMIST_API_KEY=smm_test_…   # paste the key you were shown

02Add the server§

In the project where your agent works:

Claude Code

claude mcp add smmist --transport http https://api.smmist.com/mcp \
  --header "Authorization: Bearer $SMMIST_API_KEY"

Other MCP clients

Any client that speaks streamable HTTP can use the same server. A JSON config:

mcp.json

{
  "mcpServers": {
    "smmist": {
      "type": "http",
      "url": "https://api.smmist.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SMMIST_API_KEY}"
      }
    }
  }
}

03Draft the first post§

Ask in plain words. A well-behaved agent calls the tools in this order:

whoami and list_accounts to see the org, its mode and which handles it can post to.
validate_post with the text and accounts. It returns every issue at once, each with a code (text_too_long, media_required, ig_reels_aspect) the agent can fix without asking you.
create_post with publish_at and an agent block naming itself and its model, so the audit trail records who drafted it.
get_post to read back per-target status, or get_post_audit_trail for the events.

what the agent sends

> Draft a post for @ClaudePass_HQ about the 1.4 changelog, Monday 9:30 PT.

tool smmist.validate_post
{ "text": "Changelog 1.4: session handoff across devices, now under a second.",
  "accounts": ["@ClaudePass_HQ"] }

tool smmist.create_post
{ "text": "Changelog 1.4: session handoff across devices, now under a second.",
  "accounts": ["@ClaudePass_HQ"],
  "publish_at": "2026-10-12T09:30:00-07:00",
  "agent": { "name": "claude-code", "model": "claude-opus-5-5" } }

status draft · draft_reason missing_scope · idempotency_key mcp:7d1e…

04The tools§

Each tool checks its scope on every call. Destructive tools (publish_now, cancel_post) carry the MCP destructive annotation, so clients can ask before running them.

whoami: Scoperead; What it doesOrg, scopes, mode and connected account count.
list_accounts: Scoperead; What it doesHandles, platform, status and token expiry.
get_platform_capabilities: Scoperead; What it doesLimits and rules to plan a post against.
validate_post: Scoperead; What it doesDry run against each account's platform rules. Writes nothing.
create_media_upload: Scopedraft; What it doesReserve an upload and return a presigned PUT with a curl example.
complete_media_upload: Scopedraft; What it doesConfirm the upload; checks size, type and codecs.
import_media_from_url: Scopedraft; What it doesFetch a public image or video URL (SSRF-guarded).
get_media: Scoperead; What it doesStatus and probe results: dimensions, duration, codecs.
create_post: Scopedraft (+publish); What it doesCreate on one or more accounts. Without publish it is saved as a draft.
schedule_post: Scopepublish; What it doesSchedule or reschedule for publish_at.
publish_now: Scopepublish; What it doesSend a scheduled or draft post immediately.
update_post: Scopedraft; What it doesEdit text, media, time or overrides. Voids any approval.
cancel_post: Scopepublish; What it doesCancel every target that has not gone out.
retry_post: Scopepublish; What it doesRetry failed targets after reconciling with the platform.
get_post: Scoperead; What it doesPer-target status, URLs, last error and attempts.
list_posts: Scoperead; What it doesFilter by status, account and time window.
get_post_audit_trail: Scoperead; What it doesEvery event for a post, with the chain check.
connect_account_link: Scopeadmin; What it doesA URL for the human to finish OAuth with the platform.

Tool	Scope	What it does
whoami	read	Org, scopes, mode and connected account count.
list_accounts	read	Handles, platform, status and token expiry.
get_platform_capabilities	read	Limits and rules to plan a post against.
validate_post	read	Dry run against each account's platform rules. Writes nothing.
create_media_upload	draft	Reserve an upload and return a presigned PUT with a curl example.
complete_media_upload	draft	Confirm the upload; checks size, type and codecs.
import_media_from_url	draft	Fetch a public image or video URL (SSRF-guarded).
get_media	read	Status and probe results: dimensions, duration, codecs.
create_post	draft (+publish)	Create on one or more accounts. Without publish it is saved as a draft.
schedule_post	publish	Schedule or reschedule for publish_at.
publish_now	publish	Send a scheduled or draft post immediately.
update_post	draft	Edit text, media, time or overrides. Voids any approval.
cancel_post	publish	Cancel every target that has not gone out.
retry_post	publish	Retry failed targets after reconciling with the platform.
get_post	read	Per-target status, URLs, last error and attempts.
list_posts	read	Filter by status, account and time window.
get_post_audit_trail	read	Every event for a post, with the chain check.
connect_account_link	admin	A URL for the human to finish OAuth with the platform.

05Retries are safe§

When create_post is called without an idempotency_key, the server derives one from the caller, the content, the accounts and the time. An agent that retries after a timeout gets the same post back with replayed: true, never a second post.