Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

MCP FAQs

Troubleshoot AI-client connections, authentication, uploads, and Blotato tool calls.

For setup instructions, choose your client in Connect your AI client. For tool sequences, use Agent workflows.

Can I post from Claude Code, Cursor, or Antigravity using prompts? Will Blotato create images and videos for me?

Yes. Setup is at Settings > API.

Step-by-step tutorial for Claude Cowork & Desktop: https://youtu.be/mh4Z9U-oaps

Step-by-step tutorial for setting up Claude with Blotato: https://www.youtube.com/watch?v=1dSNfnFL40c

Step-by-step tutorial for Claude Code: https://youtu.be/3HVH2Iuplqo

Once connected, you can ask Claude/Cursor/Antigravity to write your post, generate images or videos, and publish to your social accounts in a single prompt. Blotato handles content extraction, AI visuals, scheduling, and publishing.

Do I need to install anything?

Blotato's MCP server runs remotely. Follow the selected client's setup instructions. The client might still require configuration, account authorization, or restart.

For local media, the assistant also needs access to the file and an HTTP upload tool. A remote MCP connection alone does not provide access to the customer's filesystem.

Which AI tools are supported?

Use the client setup guide for the client you are configuring. ChatGPT.com, Codex, Claude.ai, Claude Desktop, Claude Cowork, and Claude Code are different clients with different setup paths.

Blotato exposes a remote MCP server at https://mcp.blotato.com/mcp. Authentication and configuration depend on the client. Do not infer support from the phrase "MCP-compatible" alone, and do not apply one client's OAuth or API-key instructions to another client.

After setup, call blotato_list_accounts. A returned empty list verifies authentication but means no connected social accounts are available for publishing yet.

Can I set up Blotato MCP inside ChatGPT (OpenAI)?

Follow the ChatGPT.com / Work tab in the client setup guide. Use the Codex tab only when the customer is using Codex.

A saved connector or completed browser redirect does not prove the connection works. Verify a blotato_list_accounts result before reporting success.

If connection fails, identify whether the failure occurred during connector creation, authorization, callback, or tool discovery. Preserve the exact error and client name. Do not replace an OAuth failure with instructions for a custom API-key header unless the selected client's documented setup supports that path.

Do I need a paid Blotato subscription?

Yes. API access (including MCP) requires a paid subscription. This keeps the platform in good standing with social media platforms by reducing spam.

Blotato shows as Connected in Claude Settings but Claude.ai returns an OAuth error

A saved connection and a successful tool call are different checkpoints.

  1. Confirm the client is Claude.ai rather than Claude Code or Codex.

  2. Check the Blotato account used during authorization and its paid-access state.

  3. Record the exact authorization or tool error.

  4. Follow client setup and authentication checks.

  5. Verify with blotato_list_accounts.

Generating an API key during a trial starts billing. Do not use that as an automatic troubleshooting step or promise it fixes every OAuth error.

MCP OAuth keeps failing with "Invalid API key or auth session" even though my subscription is active and the REST API works

Scope: MCP OAuth authentication fails while a separately authenticated REST request works.

A working REST request proves the API-key path for that account, not the MCP OAuth session. Reconnecting social accounts does not repair client authorization.

  1. Identify the exact client and failed stage: authorization, callback, tool discovery, or tool invocation.

  2. Follow that client's reconnection instructions in Connect your AI client.

  3. Retry the read-only blotato_list_accounts check.

  4. If it fails again, preserve the error and timestamp for support.

Use API-key authentication only when the selected client's documented path supports it. Do not paste local JSON configuration into an OAuth-only connector form. Keep the full key in personal configuration, including trailing = characters, and never send it in a support reply.

A missing request in the Logs does not establish the root cause. Do not claim an OAuth defect is repaired until a tool call succeeds.

Is this different from the REST API?

MCP exposes a selected set of Blotato operations as tools. REST and MCP use different request shapes and do not have identical operation coverage.

Use the tools reference for available MCP tools and REST API versus MCP for interface differences. Do not invent an MCP tool because a REST endpoint exists.

How does authentication work?

Blotato supports OAuth and API-key authentication. Use the selected client's instructions in Connect your AI client. A client accepting OAuth does not necessarily accept a custom API-key header or local JSON configuration.

Keep credentials out of replies and shared files. After configuration, verify authentication with blotato_list_accounts.

On a Claude Team or Enterprise plan and don't see "Add custom connector"?

Only a workspace admin can add custom connectors on Claude Team and Enterprise plans. This is a Claude platform restriction, not a Blotato limitation. Ask your Claude workspace admin to add the Blotato connector for your team. Individual members cannot add it themselves, and relaunching Claude Desktop does not change this.

Do I need to know which tools to call?

No. Your AI tool reads the tool descriptions and picks the right ones based on your prompt. Say what you want in natural language and the AI figures out the right sequence of calls.

What happens if a tool call fails?

The AI tool receives an error message and decides how to proceed. Common errors include:

  • Invalid API key - check your config

  • Rate limit exceeded - wait and retry

  • Account not found - connect your account in Accounts

Why did my AI agent publish to my LinkedIn company Page instead of my personal profile?

  1. Call blotato_list_accounts before creating the post.

  2. Match the LinkedIn personal profile by its name or username.

  3. Pass the personal profile's id as accountId to blotato_create_post.

  4. Omit pageId. A LinkedIn pageId targets a company Page.

  5. Open the Logs and select the request to verify its accountId and pageId.

A calendar slot labeled All LinkedIn accepts posts targeting any connected LinkedIn destination. It does not publish one post to every profile and Page. See LinkedIn destination troubleshooting.

Can I see my published or failed posts via MCP?

Yes. Use blotato_list_posts to retrieve published, failed, and scheduled posts. For example:

  • "What did I publish on Instagram last week?" → blotato_list_posts with status=published and platform=instagram

  • "Which posts failed this month?" → blotato_list_posts with status=failed

  • "Show me everything I posted recently" → blotato_list_posts with no filters

Each result includes the post text, platform, media URLs, post time, and — for published posts — the live URL. Failed posts include an error message explaining why they failed.

Note: blotato_list_schedules only returns future scheduled posts. To see published or failed post history, use blotato_list_posts.

Can I read or post comments via MCP?

Yes, for Instagram and Facebook. Use blotato_list_comments to read the comments on your published Instagram and Facebook posts, blotato_get_comment to check a single comment, and blotato_post_comment to post a top-level comment on one of your published posts. For example:

  • "Show me recent comments on my Instagram posts" → blotato_list_comments

  • "Comment 'Thanks everyone!' on my latest Instagram post" → blotato_list_posts → blotato_post_comment

  • "Did my comment post yet?" → blotato_get_comment

Posting is async: the comment returns with status queued, then reaches posted or failed. Poll blotato_get_comment with the returned ID to check. See Tools Reference and Comments API.

To auto-post a comment the moment your Instagram or Facebook post publishes, set firstComment on blotato_create_post.

Can I get analytics via MCP?

Yes. Use blotato_list_top_posts for your best posts over a time range, blotato_list_posts to find a specific published post, and blotato_get_post_analytics for one post's full history. For example:

  • "What are my top posts this week?" → blotato_list_top_posts

  • "How is my latest post doing?" → blotato_list_posts → blotato_get_post_analytics

The blotato_list_top_posts MCP tool ranks Twitter/X, Instagram, Facebook, Threads, and Bluesky posts. The Blotato web app and REST API also cover TikTok, YouTube, and Pinterest. LinkedIn analytics are not available. Metrics collect on a schedule after each post publishes. If a post shows no metrics yet or "not available," see the Analytics API reference.

Can I read or send direct messages via MCP?

Yes, for Instagram and Facebook. Use blotato_list_conversations and blotato_list_messages to list your DMs, blotato_get_conversation and blotato_get_message to open one, and blotato_send_message to reply. For example:

  • "Show me my recent Instagram conversations" → blotato_list_conversations

  • "Reply 'Thanks!' to my latest message from @jamie" → blotato_list_messages → blotato_send_message

You reply to people who already have a conversation with you. Set recipientId to the other party's id (an incoming message's senderId). Sending is async: the message returns with status queued, then reaches sent or failed. See Tools Reference and Messages API.

For Facebook and Instagram, attach up to 3 buttons or up to 13 quick-reply chips by passing buttons or quickReplies to blotato_send_message. The two are mutually exclusive. When someone taps a postback button or a chip, their next incoming message carries payload.selection with the value you set. See Buttons and Quick Replies.

Instagram renders buttons in the Instagram mobile app only. A recipient reading the conversation on instagram.com in a desktop browser sees the message text with no buttons. Pass buttons or a URL inside text, not both, since a message carrying both leaves the URL unclickable on desktop.

Can I set up DM automations via MCP?

Yes, for Instagram and Facebook Pages. A DM automation sends one direct message when someone comments on your post or sends your account a message.

  • blotato_create_automation creates it, with up to two triggers (one for comments and one for messages), keywords, the message, and up to 3 link buttons. Add followGate (Instagram only) to hold the message back until the person follows you, emailGate to hold it back until they reply with an email address, and webhook to call your own endpoint once the message sends.

  • blotato_list_automations lists your automations.

  • blotato_update_automation edits one, and publishes or moves it to draft.

  • blotato_update_automation_trigger updates a single trigger, for example to turn it on or off, without editing the rest of the automation.

  • blotato_delete_automation archives one.

  • blotato_list_automation_runs, blotato_list_automation_logs, and blotato_get_automation_analytics show what fired and what failed.

For example:

  • "Auto-DM my link to anyone who comments PRICE on my latest reel" → blotato_list_accounts → blotato_list_posts → blotato_create_automation

  • "Collect emails from Instagram comments and post them to my CRM" → blotato_list_accounts → blotato_create_automation with emailGate and webhook

  • "Why did my PRICE automation stop replying?" → blotato_list_automations → blotato_list_automation_runs

  • "Pause the comment trigger on my PRICE automation, but keep answering DMs" → blotato_list_automations → blotato_update_automation_trigger

Per-post targeting requires a tracked Blotato post ID. For an Instagram post published outside Blotato, an incoming comment creates this record. Ask the agent to read the comment, verify its account and native platformPostId, and use its non-null postId. If the required ID is unavailable, the agent should stop rather than widen a single-post request to every post. An any-post keyword automation needs your approval for the broader scope. See post targeting.

An automation is created as a draft unless you pass isActive: true. See Tools Reference and DM Automations.

Can I check or buy credits via MCP?

Yes. Use blotato_get_credits to see your remaining credits, account email, and current pricing (price per 1,000 credits and the min/max purchase quantity). Use blotato_buy_credits with a quantity (1,000 to 10,000) to get a Stripe Checkout link.

Buying credits through MCP does not charge you directly. blotato_buy_credits returns a checkoutUrl -- open it in a browser and complete payment there. Purchased credits land on the account the API key belongs to, so confirm the account email with blotato_get_credits first. Credits are non-transferable between accounts.

How do I create and publish visuals (videos, carousels, images)?

Tell your AI tool what you want to create. For example: "Make a carousel about productivity tips and post it to Instagram." The AI tool:

  1. Picks a template from your available templates

  2. Generates the visual using your prompt

  3. Waits for the visual to finish rendering

  4. Posts it to the platform you specified

Where do I get my account IDs?

You do not need account IDs when using the MCP Server. The AI tool calls blotato_list_accounts to find the right account based on your prompt. For example, if you say "post to my Twitter," the tool looks up your Twitter account automatically.

How do I post to a specific Facebook or LinkedIn page?

  1. Read the customer's requested Page name and platform.

  2. Call blotato_list_accounts and match the account and returned subaccount.

  3. Use the selected Page's ID as pageId in the publish tool.

  4. If names are ambiguous or the requested Page is missing, stop and clarify or follow account setup.

Do not choose the first returned Page or treat a requiredFields hint as the customer's destination choice. Facebook publishing requires a Page, not a personal profile. LinkedIn personal-profile publishing and Company Page publishing have different destination requirements. See Accounts and identifiers.

How do I upload a local file (image or video) from my computer?

Use Upload local media.

  1. Verify the assistant has access to the actual file and an HTTP upload tool.

  2. Call blotato_create_presigned_upload_url with the filename and extension.

  3. Send the file bytes to presignedUrl using HTTP PUT.

  4. Check upload success.

  5. Pass the returned publicUrl into the requested publishing workflow.

The MCP tool creates URLs. It does not transfer the file bytes. File access, network permissions, plan limits, and platform requirements still apply. If the client reports a sandbox or egress error, identify the blocked host before following the client-specific guidance below.

My file is too large to upload via MCP (for example HeyGen avatar videos hitting a 10MB cap)

Separate the client's local-file transfer limit from Blotato's plan limits and the destination platform's media requirements. Do not assume a universal 10 MB MCP limit.

If the file already has a URL:

  1. Confirm the URL returns the media file without an interactive login.

  2. Check the file against Media Requirements.

  3. Pass the media URL to the publishing workflow.

  4. Verify the submission result.

If the file exists only on the customer's computer:

  1. Follow Upload and prepare media.

  2. Obtain a presigned upload URL.

  3. Upload the file bytes using the required upload request.

  4. Confirm the upload succeeded before using the returned public URL.

A hosted URL avoids transferring the file through the chat attachment path. It does not remove Blotato or platform limits. A presigned URL alone does not upload the file. Uploading an existing file also does not make it a generated Visual in the Videos library.

Claude can't upload my photos or files to Blotato / "Sandbox error" / network egress blocked in Claude Cowork, Claude Desktop, or Claude Code

Claude Cowork or Desktop: fix the network-egress block

If you set up Blotato MCP in Claude Cowork or Claude Desktop and scheduling, publishing, or uploading a file fails with a sandbox, network, proxy, or egress error, you need to allow Blotato's storage domain in Cowork's network settings.

If the error says "Access to this website is blocked by your network egress settings" or names database.blotato.io, follow the allowlist steps below before switching to a public media URL.

Common symptoms (literal error strings and plain-English descriptions):

  • "Sandbox error" when scheduling or publishing a video from Claude Cowork

  • "Access to this website is blocked by your network egress settings. You can adjust this in Settings."

  • Claude tells you database.blotato.io is outside its sandbox's allowed network / not in the allowed domains, so it can't PUT or upload the files

  • Claude says it can't upload your images or videos to Blotato from the sandbox and asks you to upload them yourself and pass URLs instead

  • "The upload is blocked by a network proxy in this sandbox environment -- external PUT requests to storage endpoints aren't allowed from here."

  • "Stream closed" error during the presigned upload step

  • The sandbox proxy is blocking all outbound HTTPS calls

  • The sandbox cannot execute the PUT step / binary file uploads via PUT are blocked

  • The host SOCKS proxy, SOCKS5 tunnel, or alternate HTTP port is refused or blocked

  • Raw external HTTPS connections from the sandbox shell (curl, Python) are blocked

  • blotato_create_presigned_upload_url returns a URL but the PUT upload to that URL fails

  • Video upload silently fails before the post is created

  • Scheduling or publishing fails right after MCP setup with a network/sandbox message

  • Your Claude + Blotato + Canva automation hangs, never finishes, or "nothing publishes" -- it stalls on the media upload step

  • Claude reports it is "stuck at Blotato" or "stuck at Canva" and no post goes out

Fix:

  1. Go to Claude Cowork/Desktop > Settings > Capabilities > Allow network egress

  2. Set "Package managers only"

  3. Under Additional allowed domains, add database.blotato.io

  4. Click the "Add" button

  5. Fully quit and restart Claude Cowork/Desktop -- the allowlist only takes effect after a restart

  6. Start a new Cowork conversation and retry there -- a conversation opened before the change keeps its old, blocked sandbox even after the restart

Already added database.blotato.io but the upload still fails with 403 Forbidden / X-Proxy-Error: blocked-by-allowlist or the same egress-blocked message? Three common causes:

  1. Skipping the restart. Quit Claude completely (not only the window), then reopen it.

  2. Retrying inside the old chat. The allowlist applies to new sandboxes only. Start a new Cowork conversation and retry the upload there -- the old chat stays blocked.

  3. The egress level is still too restrictive. If your settings look correct but the upload stays blocked, change Allow network egress to "Allow all" instead of "Package managers only". Restart Claude and retry.

Which Blotato domains do I need to allowlist?

If you run Blotato from any sandboxed or firewalled environment (Claude Cowork, a hosted agent, CI, a container), allow these domains:

Domain
Used for
Needed when

mcp.blotato.com

MCP server endpoint

You connect over MCP

backend.blotato.com

REST API (https://backend.blotato.com/v2)

You call the REST API directly

database.blotato.io

Media uploads and Blotato-hosted media URLs

You upload local files, or publish media Blotato generated

If you only pass public media URLs and never upload a local file, you also need to allow whichever host serves those URLs.

Using Claude Code (not Claude Cowork/Desktop)?

Identify whether Claude Code is running locally or in a hosted environment. File access and network permissions depend on that environment. Do not assume the Cowork menu applies or that every Claude Code environment prohibits HTTP PUT.

  1. Read the exact upload error and blocked destination.

  2. Use the environment's approved file and network tools.

  3. If upload remains unavailable, ask for a public direct media URL or use an authorized environment with file and HTTP access.

  4. Check the media requirements before publishing.

A share page or login-protected URL is not a direct media file. A public URL avoids the local upload step, not Blotato's downstream limits.

Can I run Blotato from a hosted or cloud agent, with nothing on my local machine?

Yes. The Blotato MCP server runs remotely at https://mcp.blotato.com/mcp. It assumes no local terminal, no local filesystem, and no local install, so any MCP-compatible host that can reach that URL works -- including hosted and scheduled agents.

To run fully unattended:

  1. Authenticate with the blotato-api-key header. OAuth is for Claude.ai, Claude Desktop, and Claude Cowork only. See API Keys

  2. Allowlist the domains in Which Blotato domains do I need to allowlist?

  3. Pass media as public URLs, or upload to Blotato first and reference the returned publicUrl. No local file access is required at any point

  4. Pre-approve the tool calls your agent makes. Your AI host, not Blotato, prompts for per-tool permission -- an unattended run stalls if approval is still required

No step in the pipeline requires the Blotato web app. Generating captions, creating posts, scheduling, and publishing are all available over MCP and the REST API.

If you are choosing between the two for a hosted deployment, see Should I use the REST API or MCP?.

How do I edit a scheduled post via MCP (caption, media, or time)?

Call only blotato_update_schedule. It updates an existing schedule in place — it never creates a new post.

To change the caption or media: pass the whole post object, not just the field you're editing. The tool requires accountId, platform, text, plus the platform-specific fields (e.g., pageId for Facebook). If you pass a partial post (e.g., only text), the draft change is silently dropped and only scheduledTime is applied.

Recommended flow:

  1. blotato_list_schedules — find the schedule ID

  2. blotato_get_schedule — fetch the current full post object

  3. blotato_update_schedule — pass the schedule ID, the full post object with your edit applied, and scheduledTime if changing the time

To change only the time: pass id + scheduledTime. No post needed.

If you ever see two posts published for what should have been an edit, your AI tool likely also called blotato_create_post. Tell it explicitly: "use only blotato_update_schedule, do not create a new post."

Claude only posts when I tell it to. How do I make posting fully automatic?

A regular Claude chat acts only when you send a message, so posting stays manual. To automate posting completely, schedule the run instead of triggering it by hand:

  • Set up a Claude Code Routine (a scheduled agent) that runs your Blotato posting workflow on a recurring schedule -- for example, every morning.

  • Or use a Managed Agent to run the posting workflow in the cloud on a schedule. See Can I run Blotato from a hosted or cloud agent?

  • Alternatively, run the same flow from n8n or Make.com with a schedule trigger and the official Blotato nodes. See n8n FAQs and Make.com FAQs.

Didn't find your answer?

PreviousExample prompts
NextREST API quickstart

Last updated