Docs

MCP server reference

Postloom speaks the Model Context Protocol over Streamable HTTP. Any MCP client — ChatGPT, Claude, Claude Code, Gemini CLI or your own — can list accounts, preview posts per network, and create, schedule or publish them.

Endpoint

One stateless endpoint. Send JSON-RPC 2.0 messages with POST; responses are JSON. Supported protocol versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05.

MCP server URL

https://post-loom.com/api/mcp

Authentication

Every request needs a bearer token. Tokens act as the person who created them, with their current role in the workspace.

API keys (Claude Code, Gemini CLI, scripts)

Create a key in AI assistants → Create a key and send Authorization: Bearer plm_…. Keys are shown once and stored as a SHA-256 fingerprint; revoke them any time.

OAuth 2.1 (ChatGPT, Claude)

Clients discover everything from the metadata documents, register themselves and use PKCE (S256). Access tokens last one hour; refresh tokens rotate and last 30 days.

GET https://post-loom.com/.well-known/oauth-protected-resource/api/mcp
GET https://post-loom.com/.well-known/oauth-authorization-server
POST https://post-loom.com/api/oauth/register
GET https://post-loom.com/oauth/authorize
POST https://post-loom.com/api/oauth/token
POST https://post-loom.com/api/oauth/revoke

An unauthenticated request gets 401 with a WWW-Authenticate header pointing at the resource metadata.

Tools

list_accountsread-only
Lists the social accounts connected to this Postloom workspace (id, network, handle, group, sandbox or live).
arguments: none
list_mediaread-only
Lists images in the workspace media library (newest first) so posts can reference them by id.
arguments: limit
get_network_rulesread-only
Character limits, image requirements and required fields for each network.
arguments: network
preview_postread-only
Shows the exact text each target account would receive, with any problems (too long, missing image or title). Nothing is saved.
arguments: text, link, media_ids, account_ids, networks, group, all_accounts, customizations
create_postchanges data
Creates a post for the chosen accounts. With schedule_at it is scheduled; with publish_now: true it is published immediately; otherwise it is saved as a draft. Use customizations to change the text, title, images or publishing time (schedule_at) for one network or one account.
arguments: text, link, media_ids, account_ids, networks, group, all_accounts, customizations, schedule_at, publish_now
list_postsread-only
Lists recent posts with their status, scheduled time and accounts.
arguments: status, limit
get_postread-only
Returns one post with its customizations and the delivery status for each account.
arguments: post_id
update_postchanges data
Changes a draft or scheduled post. Omitted fields keep their current value. Pass schedule_at to (re)schedule it.
arguments: text, link, media_ids, account_ids, networks, group, all_accounts, customizations, post_id, schedule_at
publish_postchanges data
Publishes a draft or scheduled post immediately (or retries the accounts that failed).
arguments: post_id
unschedule_postchanges data
Moves a scheduled post back to drafts so it is not published.
arguments: post_id
delete_postchanges data
Deletes a post from Postloom. Copies already published on Bluesky and Mastodon are deleted there too (this can’t be undone); copies on other networks stay live.
arguments: post_id

Examples

List tools

curl -s https://post-loom.com/api/mcp \
  -H "Authorization: Bearer plm_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Schedule a post to every account in a group, shorter on X, with Instagram at its own time

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_post",
    "arguments": {
      "text": "This Saturday: latte art for beginners, 10:00–11:30. Six seats, all milk included.",
      "group": "Fernwood Coffee",
      "customizations": [
        {
          "network": "x",
          "text": "Latte art for beginners, Sat 10:00. Six seats ☕️"
        },
        {
          "network": "instagram",
          "schedule_at": "2026-11-07T18:30:00-05:00"
        }
      ],
      "schedule_at": "2026-11-07T09:00:00-05:00"
    }
  }
}

Errors and limits

Tool problems come back as a normal result with isError: true and a plain explanation (for example, which accounts need a shorter text).
Protocol errors use JSON-RPC codes: -32700 parse error, -32600 invalid request, -32601 unknown method, -32602 unknown tool.
Each key can make 120 requests per minute; beyond that the server answers 429 with Retry-After.
Plan limits (posts per month, accounts) apply exactly as in the app.

Questions? Contact us.