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 Instagram, Facebook Pages, Threads, TikTok, Telegram, Discord, Bluesky and Mastodon accounts (X is coming soon), 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 authenticationCopy Anchor Link

• Endpoint: https://staging.postgale.com/mcp (alias https://staging.postgale.com/api/mcp), Streamable HTTP transport, stateless.

• Sign in (OAuth 2.1): paste the endpoint into ChatGPT, Claude, Cursor or VS Code and sign in to Postgale. You pick the workspace the app may use; it then has the same access as an API key of that workspace. Connected apps are listed, and can be revoked, under Dashboard → Connected apps.

• API key: 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 or connected app).

Connect with sign-in (no API key)Copy Anchor Link

Clients that support MCP authorization only need the URL https://staging.postgale.com/mcp. They open a Postgale sign-in and consent page in the browser, then refresh their access on their own.

• ChatGPT: Settings → Apps & Connectors → Advanced → Developer mode, then Create (or Add connector), paste https://staging.postgale.com/mcp, authentication OAuth.
• Claude (claude.ai, Desktop and mobile): Settings → Connectors → Add custom connector, paste https://staging.postgale.com/mcp, then Connect.
• Claude Code: claude mcp add --transport http postgale https://staging.postgale.com/mcp, then run /mcp in Claude Code and choose Authenticate.
• Cursor and VS Code: add the server with only its URL (no headers); the editor shows a sign-in prompt.

{
  "mcpServers": {
    "postgale": {
      "url": "https://staging.postgale.com/mcp"
    }
  }
}

Approve only requests you started yourself: the consent page shows the app, where it returns to, and the workspace it gets. Tick “Hold posts from this app for approval” to send everything it creates to the approval queue.

Connect a client with an API keyCopy Anchor Link

Cursor and most clients that accept an mcpServers file:

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

Claude Code:

claude mcp add --transport http postgale https://staging.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://staging.postgale.com/mcp",
        "--header",
        "Authorization:${POSTGALE_AUTH}"
      ],
      "env": {
        "POSTGALE_AUTH": "Bearer sk_…"
      }
    }
  }
}

VS Code:

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

Raw HTTP, to check a key:

curl https://staging.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://staging.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"}'

ToolsCopy Anchor Link

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

PublishingCopy Anchor Link

• 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 messagesCopy Anchor Link

• 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.

WhatsAppCopy Anchor Link

• 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 gateCopy Anchor Link

• Approval is on by default for new organizations. When approval is required for the organization, an account, the API key or the connected app, new posts are held as pending_approval until an owner or admin approves them in the dashboard. get_api_key_info shows which rules apply.
• While approval applies, write actions that act on the accounts are queued for a person instead of running: comment replies and moderation, changes to published posts, DMs and conversations, mention and review replies, WhatsApp sends, broadcasts, flow messages and calls, Discord and Telegram writes, X engagement, account settings changes and create_webhook. The tool returns {id, status: "pending_approval", kind} and nothing reaches the platform yet; calling it again with the same input returns the same action. An approved create_webhook shows the signing secret once to the person who approves it, in the dashboard; the action's result and the action.* webhooks carry the webhook without its secret.
• An owner or admin approves it in Dashboard → Approvals (the stored call runs exactly as queued), edits the text (it then runs with their text) or rejects it. get_action and list_actions show the status: executed with the result, failed with the error, or rejected. The action.* webhooks report the same steps.
• Validation, ownership and the messaging window are checked before queueing, so errors still come back at once. Ads tools and WhatsApp business-settings writes answer approval_required instead. Reads are never blocked.

ErrorsCopy Anchor Link

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).

LimitationsCopy Anchor Link

• Sign-in (OAuth) tokens work on the MCP server only; the REST API uses API keys.
• Approving, editing and rejecting posts and queued actions is dashboard-only.
• Posts cannot be rescheduled or unscheduled: delete the post and create it again.
• API keys, connected apps, organization settings and disconnecting accounts are managed in the dashboard.

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