Postgale MCP server

Postgale runs a hosted Model Context Protocol server so AI agents (Claude, Cursor, VS Code and other MCP clients) can draft, schedule and publish posts to your connected Reddit, Instagram, Facebook Pages, Threads and TikTok accounts, moderate comments, answer direct messages, send WhatsApp messages and read analytics. It exposes the same operations as the REST API(OpenAPI spec), with the same permissions, rate limits and approval rules.

Endpoint and authentication

• Endpoint: https://postgale.com/mcp (alias https://postgale.com/api/mcp), Streamable HTTP transport, stateless.
• Authentication: Authorization: Bearer sk_… with a Postgale API key from Dashboard → API keys. The key acts for its organization only.
• Rate limit: shared with the REST API (default 60 requests per minute per key).

Connect a client

Cursor and most clients that accept an mcpServers file:

{
  "mcpServers": {
    "postgale": {
      "url": "https://postgale.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_…"
      }
    }
  }
}

Claude Code:

claude mcp add --transport http postgale https://postgale.com/mcp --header "Authorization: Bearer sk_…"

Claude Desktop, through the mcp-remote bridge (keep the key in the environment so it is not split on the space):

{
  "mcpServers": {
    "postgale": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://postgale.com/mcp",
        "--header",
        "Authorization:${POSTGALE_AUTH}"
      ],
      "env": {
        "POSTGALE_AUTH": "Bearer sk_…"
      }
    }
  }
}

VS Code:

{
  "servers": {
    "postgale": {
      "type": "http",
      "url": "https://postgale.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_…"
      }
    }
  }
}

Raw HTTP, to check a key:

curl https://postgale.com/mcp \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

curl https://postgale.com/mcp \
  -H 'Authorization: Bearer sk_…' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Mcp-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Tools

68 tools. Each declares MCP annotations (read-only, destructive, open-world) so clients can ask for confirmation before writes; the kind below follows them.

Publishing

• create_post without publishNow or scheduledFor saves a draft. scheduledFor (ISO 8601 with a time zone) schedules it. publishNow and publish_post publish live to the real platforms.
• Editing an approved post sends it back for approval. The same text cannot be posted twice within 24 hours; pass requestId to retry safely.
• Instagram, Facebook, Threads and TikTok media must be hosted: call upload_media and pass its publicUrl as mediaUrl (or in mediaUrls). Instagram images must be JPEG. TikTok requires privacyLevel. Per-platform options are listed in the REST API reference.
• Facebook Pages: one account per Page. The owner picks the Pages after opening the connect_account link. When the OAuth result is a pending selection, call select_connection without arguments to find its pendingId (it is also sent in the connection.pending webhook), then with the pendingId and no optionIds to list the Pages, then again with the chosen optionIds to connect them (within 30 minutes).
• Every write made through MCP is recorded in the organization's audit log.

Direct messages

• Instagram (permission instagram_business_manage_messages) and Facebook Page Messenger (pages_messaging). Inbound messages arrive through Meta webhooks and appear in list_conversations (and as message.received webhooks); sync_conversations backfills older threads (Meta returns details for the 20 most recent messages per conversation).
• send_message sends a live message to a real person. Meta only allows replies to people who wrote first: free-form messages within 24 hours of the participant's last message, or within 7 days with tag HUMAN_AGENT when a human writes the reply (the Meta app needs the Human Agent permission). Outside the window the tool fails with outside_messaging_window and nothing is sent; messagingWindow on each conversation shows when it closes.
• Sent messages cannot be edited or deleted. get_conversation_messages does not mark anything read; mark_conversation_read does, and sends a read receipt unless platform is false.

WhatsApp

• One account per business phone number. connect_account with whatsapp returns a link to Meta's Embedded Signup for the number's owner; whatsapp_connect_number connects a number with a token you already have.
• whatsapp_send_message (or send_message in a WhatsApp conversation) sends live messages. Free-form messages only within 24 hours of the person's last message; otherwise only an approved template, else outside_messaging_window.
• Templates: whatsapp_list_templates, whatsapp_create_template (reviewed by Meta; template.status webhook), whatsapp_delete_template. Media: whatsapp_upload_media, then send with whatsappMediaId.
• Full guide with payloads and curl examples: /docs/whatsapp.

Approval gate

• When approval is required for the organization, an account or the API key, new posts are held as pending_approval until a person approves them in the dashboard. get_api_key_info shows which rules apply.
• While approval applies, moderate_comment, reply_to_comment, manage_published_post, send_message and whatsapp_send_message are refused with approval_required. Reads are never blocked.

Errors

Tool errors carry the same message as the REST API, with the error code appended in parentheses, e.g. … Reconnect the account. (reconnect_required). A missing_permission error means the account must be reconnected after the Meta app has been granted that permission; get_account_health lists the account's missingPermissions and the features they block.

Post state conflicts are reported the same way, e.g. (APPROVAL_REQUIRED), (ALREADY_PUBLISHED), (NOT_EDITABLE).

Limitations

• MCP clients authenticate with API keys only; OAuth sign-in for MCP clients is not available yet.
• Approving and rejecting posts is dashboard-only.
• Posts cannot be rescheduled or unscheduled: delete the post and create it again.
• API keys, organization settings and disconnecting accounts are managed in the dashboard.

For plain HTTP integrations, webhook payloads and signature verification, see the REST API reference.