> 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/setup.md).

# Connect your client

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 [Blotato Settings](https://my.blotato.com/settings).
3. For an API-key setup, copy the full key from [Settings > API](https://my.blotato.com/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

{% tabs %}
{% tab title="Claude.ai" %}

1. Open [Claude connectors](https://claude.ai/customize/connectors?modal=add-custom-connector).
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](/start-with-an-ai-agent/mcp/faqs.md).
{% endtab %}

{% tab title="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](#troubleshooting).

For local media, the assistant also needs file access and permission to reach the upload destination. Follow [upload troubleshooting](/start-with-an-ai-agent/mcp/faqs.md#claude-cant-upload-my-photos-or-files-to-blotato--sandbox-error--network-egress-blocked-in-claude-cowork-claude-desktop-or-claude-code).

Video: [Claude Cowork and Desktop setup](https://youtu.be/mh4Z9U-oaps).
{% endtab %}

{% tab title="Claude Code" %}

1. Run this command in your terminal:

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

2. Open Claude Code.
3. Run `/mcp`.
4. Select Blotato and authenticate through the browser.
5. 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:

```bash
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](https://code.claude.com/docs/en/mcp) and [Blotato's Claude Code tutorials](/integrations-and-automation-templates/claude-code.md).
{% endtab %}

{% tab title="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:

```bash
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:

```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](https://learn.chatgpt.com/docs/extend/mcp).
{% endtab %}

{% tab title="ChatGPT Work" %}
For a hosted Work chat, follow the current [ChatGPT custom MCP setup](https://learn.chatgpt.com/plugins/quickstart):

1. Enable Developer mode in Settings under Security and login when available for your account.
2. Open ChatGPT Plugins and add an MCP connection.
3. Enter `https://mcp.blotato.com/mcp`.
4. Complete the connection form's authentication steps.
5. Install the resulting personal plugin.
6. Start a Work chat and select the connection.
7. Ask: “List my connected Blotato accounts using `blotato_list_accounts`.”

Workspace administrators control availability. This creates your own connection to Blotato's MCP server.

If your interface instead shows Settings > Plugins > MCPs > Add Server, select Streamable HTTP, enter the same URL, and set the `blotato-api-key` header to your full key. Leave Bearer token env var blank for this header configuration.

![Blotato MCP header configuration in the ChatGPT interface](https://2374509648-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FevfU9S4Nh53PiGflQLah%2Fuploads%2Fgit-blob-8dc85b98ab3cee148a0597c4452d5bd7729230ae%2Fchatgpt-blotato-mcp-setup.png?alt=media)

For local Codex configuration, use the Codex tab.
{% endtab %}

{% tab title="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`.”

```json
{
  "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](https://cursor.com/docs/mcp).
{% endtab %}

{% tab title="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`.”

```json
{
  "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](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).
{% endtab %}

{% tab title="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](https://my.blotato.com/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.
{% endtab %}
{% endtabs %}

## 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](/api-and-mcp-concepts/authentication.md) and the troubleshooting steps below.

After verification, choose an [agent workflow](/agent-workflows/agent-workflows.md).

## Tutorials

* [Claude + Blotato beginner setup](https://www.youtube.com/watch?v=1dSNfnFL40c)
* [Build an AI assistant for social media](https://youtu.be/3HVH2Iuplqo)
* [Claude Code tutorial](https://youtu.be/fYX6hHC9FhQ)

## Upload your own local images or videos via MCP

The Blotato MCP tools (`blotato_create_post`, `blotato_create_visual`) 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 clients (ChatGPT, Cursor, etc.):** Double check you copy/pasted the correct API key from [Settings > API](https://my.blotato.com/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. Tell your AI tool the connection is correct and point it to the help docs. For example: "My Blotato MCP is connected. Reference this doc for instructions: [Help guide](https://help.blotato.com/api/llm)"
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](/api-and-mcp-concepts/authentication.md). 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 [Settings](https://my.blotato.com/settings) 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](https://my.blotato.com/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](https://www.youtube.com/watch?v=1dSNfnFL40c) and [Build Your AI Personal Assistant for Social Media Marketing](https://youtu.be/3HVH2Iuplqo)


---

# 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/setup.md?ask=<question>&goal=<endgoal>
```

`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.