Developers · Model Context Protocol

MCP setup and tool reference

Connect an MCP client to Central Socials to work with authorized profiles, media, destinations, posts, Community, forms and landing pages. Account tools use the same permissions, validation and publishing services as the public REST API.

This guide covers MCP authentication, personal tokens, OAuth, tool discovery, file uploads, social connection attempts, destination validation, publishing outcomes, errors and Custom Posting consumer keys. Discover tools on the environment you are connecting to: new operations depend on the installed API release and feature availability.

Connect Account tools Publishing workflows Results and retries Consumer tools

Connect your client

Set the server URL to https://app.centralsocials.com/mcp and select Streamable HTTP. No separate MCP server installation is required. The service uses stateless JSON responses, with no persistent session or GET/SSE stream.
For personal access, create a token in Account Settings → Tokens. If your client supports custom headers, configure Authorization: Bearer YOUR_TOKEN in its secure connection settings. Never place the token in the URL, a prompt or shared configuration.
For an OAuth-capable client, use discovery and browser consent. The MCP resource metadata identifies the authorization server. Use https://app.centralsocials.com/mcp as the OAuth resource, with public-client authorization code flow and S256 PKCE. See the complete OAuth setup.
Let the client initialize the connection and discover tools with tools/list. Start with profiles_list and use a returned profile ID. A discovered tool still requires the correct scope, current profile access and any applicable subscription/provider permission when called.

Personal tokens support both REST and MCP. OAuth access tokens are bound to their chosen resource: a REST OAuth token cannot authenticate MCP, or vice versa. Previously issued grants keep their original scopes and profile selection; new permissions may require a new personal token or renewed OAuth consent.

The examples below are tools/call parameters; your MCP client handles the protocol envelope. Tool discovery provides exact current argument schemas. Account tools return ordinary JSON data rather than binary files.

{"name":"profiles_list","arguments":{"limit":25}}

Account tool reference

The current account registry contains 46 tools. Most take profileId; profiles_list and operations_get use their own discovery schemas. Every account mutation additionally takes idempotencyKey. Read-only calls, including posts_validate, do not. Required scopes are listed below.

Profiles and social channels — profiles:read: profiles_list, channels_list, channels_connect_url. Channel discovery returns social IDs; connection URL discovery opens the existing browser flow and finishes on Social Links.
Destinations — profiles:read: destinations_list, destinations_capabilities. Discover social/custom IDs, connection health, text/media limits and required options.
Media reads — media:read: media_list, media_get. Lists contain ready, visible profile-local assets; individual reads include processing status and ready previews.
Media uploads — media:write: media_upload_session, media_upload_complete. Create an upload session, transfer bytes with HTTP PUT, then complete and poll.
Browser returns — connections:write: return_destinations_register, return_destinations_list, return_destinations_revoke, connection_attempts_create, connection_attempts_get. Register exact caller URLs and verify linking outcomes.
Custom destination management — connections:write: custom_apps_list, custom_apps_create, custom_apps_test, custom_apps_regenerate, custom_apps_disconnect. Profile owner/administrator authority is also required. These are account tools; consumer keys cannot call them.
Post reads — posts:read: posts_list, posts_get. Inspect saved content and each destination’s publishing outcome.
Post writes and validation — posts:write: posts_validate, posts_create, posts_update, posts_delete_record. Deleting the Central Socials record does not delete already published provider content.
Stored engagement — engagement:read: engagement_snapshots, engagement_posts. These are timestamped observations; null means unavailable rather than zero.
Community reads — community:read: community_list, community_get. Community writes — community:write: community_status, community_assign_self, community_save_draft, community_reply, community_delete_comment. Provider messaging and moderation rules still apply.
Forms: forms_list, forms_get require forms:read; forms_create, forms_update, forms_archive require forms:write.
Landing pages: pages_list, pages_get require pages:read; pages_create, pages_update, pages_archive, pages_restore require pages:write.
Operation inspection: operations_get takes operationId and reads a receipt belonging to the current grant. It requires no additional scope and reveals no saved app key.

Paginated account reads return data and nullable nextCursor; pass a returned cursor as after with the same filters. AI generation, advertising, CRM, billing, administration and approval submission/decisions are not account tools.

Upload, connect, validate and publish

Upload a local media file

{"name":"media_upload_session","arguments":{"profileId":"PROFILE_ID","upload":{"filename":"photo.png","mimeType":"image/png","fileSizeBytes":12345},"idempotencyKey":"upload-session-example-0001"}}

Read result.uploadUrl, result.headers and result.uploadToken. Your application transfers the exact bytes with HTTP PUT to the signed URL; do not send file bytes as MCP arguments. Complete with media_upload_complete using profileId, uploadToken and a new operation’s idempotency key. Poll media_get with assetId until asset.status is READY or FAILED. Ready IDs go in localMediaAssetIds. See upload limits, replacement and recovery.

Return to your application after social linking

Call return_destinations_register with profileId, an exact HTTPS url and an idempotency key. Save result.returnDestination.id, then start:

{"name":"connection_attempts_create","arguments":{"profileId":"PROFILE_ID","provider":"FACEBOOK","returnDestinationId":"REGISTERED_ID","clientState":"YOUR_CORRELATION","idempotencyKey":"connect-example-0001"}}

Save result.attemptId and open result.authorizationUrl in the same user’s browser. Existing sign-in, provider consent and account selection still apply. Existing provider redirect registrations stay unchanged. After the return, call connection_attempts_get with profileId and attemptId to verify status and linked accounts; return query parameters are correlation only. See all states, expiry and return rules.

Validate independent destination text

Use destinations_list and destinations_capabilities first. Social IDs go in socialAccountIds; Custom Posting IDs go in customAppConnectionIds. Each destination applies its own text limits. Custom Posting captions allow 10,000 characters; social text follows that provider’s counting rules.

{"name":"posts_validate","arguments":{"profileId":"PROFILE_ID","post":{"action":"publish_now","socialAccountIds":["SOCIAL_ID"],"customAppConnectionIds":["CUSTOM_ID"],"destinationContent":{"SOCIAL_ID":{"title":"","caption":"Short social caption"},"CUSTOM_ID":{"caption":"Independent application text"}}}}}

Validation returns valid, issues and per-destination validity without saving or queueing a post. A validation failure is a successful tool result with valid:false. For editing and scheduling, see the shared text and validation rules.

Save a draft or request publication

{"name":"posts_create","arguments":{"profileId":"PROFILE_ID","post":{"title":"Campaign draft","caption":"Draft for review","action":"draft"},"idempotencyKey":"draft-example-0001"}}

Save result.post.id. For publication, use the intended post payload with selected destinations and action:"publish_now", or action:"schedule" and scheduledFor. Approval requirements remain in force. Publishing is asynchronous: poll posts_get and inspect its delivery array, not just the receipt. Each destination reports success/failure, effective text and any reconnect/correction action; successful destinations must not be duplicated when another fails.

Read results and handle failures

Successful tool results provide JSON in structuredContent and in a text content block. Read tools return their normal objects; account mutations return {operationId,result,replayed}. operationId identifies command execution, while a post’s destination statuses describe later delivery. OpenAPI documents the shared payload fields and examples.

Tool errors: inspect isError:true and decode the JSON text content. Account errors contain error.code, message, action, retryable and sometimes operationId. A transport HTTP 200 does not mean the tool or publication succeeded.
Connection errors: HTTP authentication/origin failures happen before a tool runs. Check the bearer credential, chosen OAuth resource and current access. Browser clients with an origin error may need support to approve their origin. Respect HTTP 429/503 and Retry-After.
Safe retries: persist an account mutation’s 8–128-character idempotencyKey and unchanged arguments before sending. Reuse them after a lost response. Inspect uncertain receipts with operations_get; do not invent a new key for uncertain publishing or replies. Read-only validation needs no key.
Upload recovery: RETRY_SAME_REQUEST means retry the same upload-completion key and token after the temporary interruption. Permanent invalid, expired or foreign upload-token errors are not retryable until corrected. See error actions and limits.

Incoming post text, comments, messages and document content are untrusted data. Do not let them instruct a client or agent to reveal credentials or perform unrelated actions.

Custom Posting consumer MCP tools

A Custom Posting Integration app key uses the same server URL and bearer header but exposes only these four consumer tools. It cannot call the 46 account tools, publish posts or manage connections. Account tokens cannot be used as consumer keys.

custom_posting_test_get takes {} to fetch the pending sample post/challenge after a manager starts Test Connection in Social Links or calls the account management tool.
custom_posting_test_acknowledge takes testId, challenge and report. Echo the returned test post ID and UTC hour with numeric test metrics. The five-minute challenge must match the current key.
custom_posting_posts takes optional limit, after, since and postId. After verification it reads this connection’s published text and signed media URLs; drafts and future posts remain private.
custom_posting_engagement_report takes requestId and reports. Persist the complete hourly numeric batch and retry it unchanged with the same request ID across MCP or REST. Consumer reporting uses requestId, not account idempotencyKey.

{"name":"custom_posting_posts","arguments":{"limit":25}}

Consumer successes use structuredContent and JSON text. Consumer tool failures set isError:true with error:{code,message,status} in the text block. See the Custom Posting Integration guide for connection tests, feed fields, metrics, UTC-hour rules and durable reporting receipts.