Mellow Hub — publishing through an agent

Mellow Hub publishes one post to many social networks and checks every network's own rules before anything goes out. You reach it two ways, and both resolve to the same functions:

• MCP (preferred): https://www.mellow.world/mcp — Streamable HTTP, OAuth 2.1 with dynamic client registration and PKCE, or an owner-issued API key as the bearer. 21 tools, 4 guide resources, 3 prompts.
• REST: https://www.mellow.world/api/hub/v1 — Authorization: Bearer mk_live_… (an API key the owner creates at https://www.mellow.world/hub/agents).

Full reference: https://www.mellow.world/hub/docs (the same text as https://www.mellow.world/hub/llms.txt and the MCP resource mellow://guide/start).

1. Connect

MCP with OAuth (Claude Code, Claude.ai, ChatGPT, Cursor, Hermes, OpenClaw…)

Claude Code:

claude mcp add --transport http mellow https://www.mellow.world/mcp

Then authenticate when the client asks; the server answers the first request with a 401 that points to /.well-known/oauth-protected-resource, and a client that supports OAuth discovery completes registration, PKCE and the consent screen by itself. The person approves on the consent screen: which channels, which scopes, review or autopilot, a daily ceiling (1–1000, default 50) and an expiry (1–30 days, default 7). Only channels:read and posts:read are pre-checked and the default mode is review, so if you need to publish, ask the person to tick posts:write, posts:publish, media:write and choose autopilot.

Generic mcp.json (Cursor, Codex, OpenClaw and other clients that read this shape):

{
  "mcpServers": {
    "mellow": {
      "type": "http",
      "url": "https://www.mellow.world/mcp"
    }
  }
}

If the client cannot do OAuth, an API key works as the bearer on the same endpoint (never paste it into chat; read it from the environment):

{
  "mcpServers": {
    "mellow": {
      "type": "http",
      "url": "https://www.mellow.world/mcp",
      "headers": { "Authorization": "Bearer ${MELLOW_HUB_KEY}" }
    }
  }
}

Hermes: hermes mcp add --url https://www.mellow.world/mcp --auth oauth mellow then hermes mcp login mellow.

REST with an API key

The owner creates a key at /hub/agents (POST /api/hub/v1/keys takes name, scopes, mode, channelScope, dailyPostLimit — default 50 — and expiresInDays). Default key scopes are channels:read media:write posts:read posts:write posts:publish metrics:read; channels:connect and ai:generate must be added on purpose. Keys start with mk_live_ and are bound to one profile — a profile header cannot switch them.

curl --fail-with-body https://www.mellow.world/api/hub/v1/whoami \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

2. The required call order

Always in this order. Each step's answer changes what the next may do.

Optional afterwards: preview_post (how it will read per network; needs a valid post), list_posts (find a post after a timeout), reschedule_post, cancel_post (needs confirm: true), get_metrics (needs metrics:read), list_platforms (needs no scope).

3. Idempotency keys — non-negotiable

• create_post refuses a request without idempotencyKey: 8–120 characters from A-Z a-z 0-9 _ . : -.
• Derive it from the task, not at random: week-38-tue-morning, blog-142-linkedin, client-acme-launch-2026-09-25.
• A timeout is not a refusal. Retry the same request with the same key: Mellow returns the original post instead of a second publication.
• Reusing a key for different content is refused with idempotency_key_reused (409). Do not generate a new key to get past it — compare with what you sent before.
• Recovering a partial post uses a new key and names only the failed channels.

4. The post

{
  "caption": "The long version, written for LinkedIn…",
  "media": ["https://cdn.example.com/clip.mp4"],
  "channels": ["spc_linkedin", "spc_bluesky", "spc_x", "spc_youtube"],
  "scheduledAt": "2026-09-25T10:00:00Z",
  "options": {
    "youtube": { "title": "Why we rebuilt the editor", "privacyStatus": "public" }
  },
  "perChannel": {
    "spc_bluesky": { "caption": "The short version." },
    "spc_x": { "caption": "The short version." }
  },
  "idempotencyKey": "editor-rebuild-2026-09-25"
}

• caption — one text for the post (up to 63,206 characters overall; each network has its own limit, checked per channel).
• media — ordered list, up to 35 items; each a public https URL or { url, thumbnailUrl?, thumbnailTimestampMs?, tags? }. tags mark accounts on the picture (Instagram and Facebook only, max 20) — not collaborators.
• channels — 1 to 25 spc_… ids, no duplicates.
• scheduledAt — ISO 8601 with a timezone, in the future; omit to publish now.
• options — per-network settings keyed by platform id; applies to every channel of that network.
• perChannel — overrides for one channel (caption, media, that network's options); wins over options. This is how Bluesky gets 300 characters while LinkedIn keeps 3,000.
• draft: true — keep it in Mellow, send nothing (free of the monthly allowance; still counts toward the credential's daily ceiling).

Platform ids: instagram, tiktok, tiktok_business, youtube, x, linkedin, threads, bluesky, pinterest, facebook.

5. Per-network rules (from Mellow's platform registry)

Video thumbnails: thumbnailUrl on the media item where the network accepts one (Instagram, TikTok Business, YouTube, Facebook). Mellow does not download media, so duration, resolution and aspect ratio are the network's own judgement — passing validate_post does not settle them.

6. Errors and what to do

Every error carries code, a sentence and retryable. If retryable is false, the same request will fail the same way; change the request or stop.

7. The human stays in the loop

• Connecting an account is not yours to do. connect_channel returns a URL and a sentence saying who has to open it; Bluesky additionally needs a handle and an app password typed by the person. Pass both on and wait; then list_channels with refresh: true. The link lives ten minutes.
• Review mode means "prepare and stop". whoami.mode === "review" → create_post yields pending_review; tell the person it is waiting for approval in Mellow. Approval is refused to any non-person actor (approval_requires_person).
• Studio credits are money. studio_generate spends AI credits (outline 2, cover/illustration 10) and needs the explicit ai:generate scope. Quote first with studio_quote, then ask before spending unless the person already delegated that expense. Buying credits or changing a plan is never done by an agent.
• Publishing is public and cannot be undone. Say so before an immediate create_post when the person did not explicitly ask to publish now.

8. Safety rules

1. Never publish under a mode the person did not choose: read whoami and act within mode, scopes and channels. Do not ask for a broader key to work around a refusal.
2. Respect the daily ceiling: check postsRemainingToday before a batch; if a plan needs more posts than remain, tell the person instead of spreading them over credentials or keys.
3. Validate every post, every time, before create_post. Never send a partial post again in full.
4. One stable idempotency key per post; the same key on retry; a new key only for genuinely new content.
5. Never echo, log or store an API key, an OAuth token or a signed uploadUrl. Refer to keys as $MELLOW_HUB_KEY.
6. Do not fabricate results: a create_post response is not a publication. Report targets[].status and the public url from get_post.
7. Everything you do is journaled for the owner (hub_audit_events) and visible at /hub/agents; act as if the journal will be read.

9. REST quick reference

Base https://www.mellow.world/api/hub/v1, header Authorization: Bearer $MELLOW_HUB_KEY, JSON bodies, camelCase.

Validate then create, with the public example from https://www.mellow.world/hub/guides/schedule-posts-api (edit post.example.json first — the spc_… ids and the media URL are placeholders):

curl --fail-with-body https://www.mellow.world/api/hub/v1/validate \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @post.json

curl --fail-with-body https://www.mellow.world/api/hub/v1/posts \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: studio-process-video-slot-001" \
  --data-binary @post.json

A dependency-free input checker that lists channels and validates a file without creating anything: https://www.mellow.world/hub/examples/mellow-hub-check.mjs (node mellow-hub-check.mjs --channels, node mellow-hub-check.mjs post.json; Node 22+).

10. Creative Studio (optional)

studio_list → studio_quote(kind) → ask → studio_generate(request, maxCredits, idempotencyKey) → poll studio_job → studio_project / studio_save (free edits, current revision required) → studio_export (free JPEGs). Use exported carousel URLs as media in validate_post / create_post; attach a cover as thumbnailUrl on the video item, keeping the video. Formats 4:5, 1:1, 9:16, 16:9. Export never publishes.