Connect your client

Client-specific MCP configuration and authorization for Claude, Codex, ChatGPT, Cursor, VS Code, and other clients.

Choose your client below. Blotato's MCP server runs remotely at https://mcp.blotato.com/mcp using Streamable HTTP.

Before you start

1. Confirm your paid Blotato subscription. API and MCP access is not included in the free trial.

2. Connect social accounts in Accounts.

3. For an API-key setup, copy the full key from Settings > API. Generating a key during a trial ends the trial and starts billing.

An account connection is needed for publishing. You still receive a successful empty account list before connecting social accounts.

Choose your client

Open Settings > API for the client chooser. Select the app you use, not another app with a similar chat interface. ChatGPT.com and ChatGPT Work / Codex have separate setup instructions. A Blotato subscription is separate from your AI client's subscription.

After setup, ask your client to list connected Blotato accounts. A Connected badge alone does not verify a tool call. A successful empty list means the connection works but no social accounts are connected.

Settings API client chooser and MCP setup controls without credentials

Claude.ai

1. Open Claude connectors.

2. Add a custom connector named Blotato.

3. Enter https://mcp.blotato.com/mcp as the URL.

4. Connect and approve access in the browser.

5. Ask: “List my connected Blotato accounts using blotato_list_accounts.”

Log into the intended Blotato account in the browser during authorization. If access fails, follow OAuth troubleshooting.

Claude Desktop / Cowork

1. Open Customize, then Connectors.

2. Add a custom connector named Blotato.

3. Enter https://mcp.blotato.com/mcp as the URL.

4. Connect and approve access in your browser.

5. Ask: “List my connected Blotato accounts using blotato_list_accounts.”

On a managed workspace, ask the workspace admin if adding connectors is restricted. If authorization repeatedly fails after reconnecting, follow the stale-session steps.

For local media, the assistant also needs file access and permission to reach the upload destination. Follow upload troubleshooting.

Video: Claude Cowork and Desktop setup.

Claude Code

1. Run this command in your terminal:

claude mcp add --transport http blotato https://mcp.blotato.com/mcp

1. Open Claude Code.

2. Run /mcp.

3. Select Blotato and authenticate through the browser.

4. Ask: “List my connected Blotato accounts using blotato_list_accounts.”

For an API-key setup instead of OAuth, use this command when adding the server. Replace the placeholder with your full API key:

claude mcp add --transport http blotato https://mcp.blotato.com/mcp --header "blotato-api-key: YOUR_API_KEY"

If Blotato is already configured, manage that entry through /mcp before adding it again. Keep API keys out of shared project configuration.

See Claude Code's MCP documentation and Blotato's Claude Code tutorials.

Codex

1. Open Settings, then MCP servers, and add a server.

2. Name it blotato.

3. Select Streamable HTTP.

4. Enter https://mcp.blotato.com/mcp as the URL.

5. Under Headers, set blotato-api-key to your full API key.

6. Leave Bearer token env var blank when using the header above.

7. Save and restart the MCP connection or client.

8. Ask: “List my connected Blotato accounts using blotato_list_accounts.”

For Codex CLI with OAuth:

codex mcp add blotato --url https://mcp.blotato.com/mcp
codex mcp login blotato

For an API key in Codex's ~/.codex/config.toml, use TOML:

[mcp_servers.blotato]
url = "https://mcp.blotato.com/mcp"
http_headers = { "blotato-api-key" = "YOUR_API_KEY" }

Replace the placeholder and keep the key in your personal configuration. The CLI also supports a bearer-token environment variable if your environment supplies it.

See OpenAI's MCP configuration guide.

ChatGPT.com / Work

Use OpenAI's custom MCP connection flow on ChatGPT.com:

1. Enable Developer mode in Settings → Security and login.

2. Open ChatGPT Plugins.

3. Select the + button.

4. Enter the name Blotato, a description, and server URL https://mcp.blotato.com/mcp.

5. Choose OAuth authentication.

6. Create the connection.

7. Complete the Blotato sign-in and review the requested access before approving.

8. Start a new chat with Blotato selected in the tools menu.

9. Ask: “List my connected Blotato accounts using blotato_list_accounts.”

If the plugin exists but has no connected account, open Settings → Plugins → Blotato → Connect another account → Sign in with Blotato. Adding the plugin and authorizing an account are separate steps.

“No app tools available yet” means the setup has not passed verification. Check account authorization and tool discovery before retrying the prompt. If sign-in fails, record the error and follow authentication troubleshooting. Do not describe the connection as working until a tool call succeeds.

Availability depends on your account and workspace policy. This creates a custom connection, rather than installing a Blotato listing from the public directory. For local Codex configuration, use the Codex tab. Codex does not use ChatGPT.com's Developer mode toggle.

Cursor

1. Open your personal ~/.cursor/mcp.json configuration.

2. Add the Blotato entry below, preserving any existing servers.

3. Replace YOUR_API_KEY with your full key.

4. Save and restart Cursor.

5. Ask: “List my connected Blotato accounts using blotato_list_accounts.”

{
  "mcpServers": {
    "blotato": {
      "url": "https://mcp.blotato.com/mcp",
      "headers": {
        "blotato-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Use Cursor's personal configuration for a literal API key. For variable substitution and workspace configuration, see Cursor's MCP documentation.

VS Code

For VS Code's MCP configuration:

1. Open .vscode/mcp.json in your workspace, preserving any existing servers.

2. Add the configuration below.

3. Start the Blotato server from the editor's MCP controls.

4. Enter your full Blotato API key when prompted.

5. Ask the chat assistant: “List my connected Blotato accounts using blotato_list_accounts.”

{
  "inputs": [
    {
      "type": "promptString",
      "id": "blotato-api-key",
      "description": "Blotato API key",
      "password": true
    }
  ],
  "servers": {
    "blotato": {
      "type": "http",
      "url": "https://mcp.blotato.com/mcp",
      "headers": {
        "blotato-api-key": "${input:blotato-api-key}"
      }
    }
  }
}

This uses VS Code's servers format, rather than Cursor's mcpServers format. Interactive input variables apply to the extension host. For VS Code Agent Host configuration and restrictions, follow the VS Code MCP reference.

Other clients

For Antigravity, Replit Agent, or another remote-MCP client:

1. Open the client's MCP configuration.

2. Select Streamable HTTP.

3. Set the URL to https://mcp.blotato.com/mcp.

4. Complete OAuth if supported, or set a blotato-api-key header to your full API key.

5. Reload the connection.

6. Ask the assistant to call blotato_list_accounts.

Some clients accept the JSON copied from Settings > API under Other MCP Clients. Check the client's configuration format before pasting it. Codex uses TOML, and VS Code uses a different JSON wrapper.

For a form with a Headers section, enter the full key as the value for blotato-api-key. Leave Bearer token env var blank when using this header.

Verify your connection

The verification call is blotato_list_accounts. It returns an array containing account IDs, platforms, names, and subaccounts. An empty array is a valid result when you have no connected accounts.

If no tool call runs, check whether the client enabled the connection. If the call returns an error, use the authentication guide and the troubleshooting steps below.

After verification, choose an agent workflow.

Tutorials

• Claude + Blotato beginner setup

• Build an AI assistant for social media

• Claude Code tutorial

Upload your own local images or videos via MCP

The Blotato MCP tools, such as blotato_create_post, do not accept local file paths. Media must be a publicly accessible URL. Allowlisting egress to database.blotato.io is necessary but not enough on its own. You still upload the file first.

To use a local file:

1. Call blotato_create_presigned_upload_url with your filename (include the extension). It returns a presignedUrl and a publicUrl.

2. Upload the raw file bytes to presignedUrl with an HTTP PUT (for example curl -X PUT "<presignedUrl>" --data-binary "@<local_file>"). Send raw bytes, not JSON and not multipart form data.

3. Pass the returned publicUrl in the mediaUrls field of blotato_create_post.

Do not pass the local file directly to blotato_create_post. If you allowlisted database.blotato.io but the upload still fails, the file was likely sent directly instead of being PUT to the presigned URL, or the PUT used the wrong body encoding.

---

Troubleshooting

If the MCP server connects but does not work as expected:

1. OAuth clients (Claude.ai, Desktop, Cowork, Claude Code): Make sure you are logged into your Blotato account in the browser. The OAuth approval requires an active Blotato session.

2. API-key connections (for example, Cursor or a Codex header configuration): Double check you copy/pasted the correct API key from Settings > API. Make sure there are no extra spaces or missing characters. If your key ends with one or more = characters, copy the full key including the trailing =, since dropping it causes a 401 "invalid API key" error.

3. Reload or restart the client after saving its MCP configuration.

   • OAuth authorization fails: Check the client-specific tab. If the client supports API-key headers, use that tab’s API-key configuration. Codex uses TOML and header form fields. Cursor uses JSON. Do not paste one client’s configuration into another client.

4. Give your assistant the agent reference and ask it to call blotato_list_accounts. Reading documentation does not install the MCP server, authorize an account, or expose tools to a chat.

5. If the connector shows "Connected" but a tool fails, inspect the returned error. A subscription-related 403 requires an active paid plan. A 401 points to credentials or session authentication. Follow authentication checks. Generating an API key during a trial starts the paid subscription.

6. An empty account list is a successful call. Connect a social account in Accounts before publishing.

7. For a JSON parsing error, use your editor's local JSON validation. Check for missing commas and unmatched braces. Do not paste configuration containing an API key into an online validator.

8. Connector shows "Connected" but never authenticates (stale connector session). If the Blotato connector in Claude Cowork or Claude Desktop shows Connected but every tool call fails with a credential error, and reconnecting does not help, the client is reusing a stale cached session. A simple reconnect reuses that same cached session, so remove it fully and add it fresh:

   1. Go to Customize > Connectors and fully remove the Blotato connector

   2. Click the + button, choose Add custom connector, and approve access again

   3. To double-check the key itself, see Settings > API

9. "Access to this website is blocked by your network egress settings" during a presigned upload. Claude Cowork and Claude Desktop block outbound network access by default, so the PUT to the presigned upload URL cannot reach database.blotato.io. To allow it:

   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 and click Add

   4. Fully quit and restart Claude Cowork/Desktop

   5. If your settings look correct but the upload stays blocked, set Allow network egress to "Allow all" instead of "Package managers only", then restart and retry

Video walkthroughs: Claude + Blotato Beginner Setup and Build Your AI Personal Assistant for Social Media Marketing