> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/start-with-an-ai-agent/mcp/faqs.md). # MCP FAQs Troubleshoot AI-client connections, authentication, uploads, and Blotato tool calls. For setup instructions, choose your client in [Connect your AI client](/start-with-an-ai-agent/mcp/setup.md). For tool sequences, use [Agent workflows](/agent-workflows/agent-workflows.md). ## 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](https://my.blotato.com/settings/api). Step-by-step tutorial for Claude Cowork & Desktop: Step-by-step tutorial for setting up Claude with Blotato: Step-by-step tutorial for Claude Code: 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](/start-with-an-ai-agent/mcp/setup.md). 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](/start-with-an-ai-agent/mcp/setup.md) 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](/start-with-an-ai-agent/mcp/setup.md). 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](/start-with-an-ai-agent/mcp/setup.md) and [authentication checks](/api-and-mcp-concepts/authentication.md). 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](/start-with-an-ai-agent/mcp/setup.md). 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](/start-with-an-ai-agent/mcp/tools.md) for available MCP tools and [REST API versus MCP](/api-and-mcp-concepts/rest-vs-mcp.md) 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](/start-with-an-ai-agent/mcp/setup.md). 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](https://my.blotato.com/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](https://my.blotato.com/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](/social-accounts-and-platform-faqs/linkedin/faqs.md#why-did-my-linkedin-post-go-to-my-company-page-instead-of-my-personal-profile). *** ## 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](/start-with-an-ai-agent/mcp/tools.md) and [Comments API](/rest-api-reference/comments.md). 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](/rest-api-reference/analytics.md). *** ## 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](/start-with-an-ai-agent/mcp/tools.md) and [Messages API](/rest-api-reference/messages.md). 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](/start-with-an-ai-agent/mcp/tools.md#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](/rest-api-reference/dm-automations.md#trigger-object). An automation is created as a draft unless you pass `isActive: true`. See [Tools Reference](/start-with-an-ai-agent/mcp/tools.md#automations) and [DM Automations](/web-app-features/dm-automations.md). *** ## 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](/settings/social-accounts.md). 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](/api-and-mcp-concepts/accounts-and-identifiers.md). ## How do I upload a local file (image or video) from my computer? Use [Upload local media](/agent-workflows/agent-workflows/upload.md). 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](/rest-api-reference/publish-post/media.md). 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](/agent-workflows/agent-workflows/upload.md). 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](/rest-api-reference/publish-post/media.md) 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](/settings/api-keys.md) 2. Allowlist the domains in [Which Blotato domains do I need to allowlist?](#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?](/start-with-an-ai-agent/faqs.md#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?](#can-i-run-blotato-from-a-hosted-or-cloud-agent-with-nothing-on-my-local-machine) * Alternatively, run the same flow from n8n or Make.com with a schedule trigger and the official Blotato nodes. See [n8n FAQs](/integrations-and-automation-templates/n8n/faqs.md) and [Make.com FAQs](/integrations-and-automation-templates/make.com/faqs.md). *** **Didn't find your answer?** * [General FAQs](/support/faqs.md) * [API FAQs](/start-with-an-ai-agent/faqs.md) * [n8n FAQs](/integrations-and-automation-templates/n8n/faqs.md) * [Make.com FAQs](/integrations-and-automation-templates/make.com/faqs.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.blotato.com/start-with-an-ai-agent/mcp/faqs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.