MCP Tools Reference

This page documents the eleven tools the SocialRails MCP server exposes. If you have not connected yet, start with MCP Server Setup.

Every tool maps onto an endpoint of the Public API and runs the same validation, so anything documented in API Endpoints about limits and behaviour holds here too.

All tools at a glance

Reading

list_accounts

No arguments. Returns each connected account with its id, provider, name and status. Status is connected, needs_reauth or expired.

Worth calling before scheduling. A post created for a platform whose token has expired will be accepted and then fail at publish time.

get_workspace

No arguments. Returns the workspace, its plan, and this month's usage against the plan limits. Useful when an assistant needs to know how much headroom is left before scheduling a batch.

list_posts

get_post

Returns one post. If publishing failed, the reason is in error_message.

get_analytics

Writing

create_post

Creates one post for one platform. Omit scheduled_for and it is saved as a draft.

Note that thread replaces content with its first item, so the two are not additive.

create_post_batch

The same content across up to nine platforms in one call. Each platform counts as one post against your monthly limit.

update_post

Only drafts and scheduled posts can be updated. Published posts return an error.

delete_post

Only drafts and scheduled posts can be deleted. A published post cannot be removed from the platform through the API.

generate_content

This spends AI credits from your plan. When you are already talking to a capable assistant, it will usually write the copy itself, which costs you nothing. Reach for this tool when you specifically want SocialRails AI.

Attaching media

Media is a two step flow, and this is the part assistants most often get wrong on the first try.

1. Call upload_media_from_url with a public HTTPS URL. It returns a key.
2. Pass that key in the media array of create_post or create_post_batch.

Limits: images up to 10MB (JPEG, PNG, GIF, WebP), MP4 video up to 100MB, PDF up to 100MB. For a video post, upload the video and a thumbnail image, then pass both keys.

PDFs publish as LinkedIn document carousels. LinkedIn only, one PDF per post, no other media alongside it.

Example of the full sequence:

upload_media_from_url { "url": "https://example.com/launch.jpg" }
  returns { "key": "abc123/api-uploads/images/def456.jpg" }
 
create_post {
  "content": "Our new pricing is live.",
  "platform": "linkedin",
  "scheduled_for": "2026-09-11T09:00:00Z",
  "media": ["abc123/api-uploads/images/def456.jpg"]
}

Media keys are scoped to your workspace. A key from another workspace is rejected.

Errors

Tool errors come back as readable text with the API error code in front, so the assistant can act on them rather than guessing:

FORBIDDEN: API key does not have write scope.

LIMIT_EXCEEDED: Monthly post limit reached (900/900 posts). Upgrade your plan for more.

BAD_REQUEST: Field "scheduled_for" must be in the future.

The codes are the same ones the REST API returns. See API Errors for the full list.

Two failures are worth calling out because they are not tool errors and will surface differently in your client:

• 401 on every call. An authentication problem, not a tool problem. Check the header.
• 429 on every call. You have exhausted the hourly request limit. An assistant in a retry loop can do this quickly.

Things the tools do not do

• One post, one platform. create_post targets a single platform. Use create_post_batch for several.
• No publishing straight away. Posts are created as drafts or scheduled. There is no publish-right-now tool.
• No account management. Connecting and reconnecting social accounts happens in the dashboard.
• No webhook management. Webhooks are REST only. See API Webhooks.
• No file uploads. Media must be reachable at a public HTTPS URL. There is no way to hand raw bytes to an MCP tool.