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

# Setup Guide

Setting up Blotato with Claude, Antigravity, or Cursor takes a few minutes.

Generate your API key: [Settings > API](https://my.blotato.com/settings/api)

## Tutorials

Using **Claude.ai Web**? Add Blotato directly here: <https://claude.ai/customize/connectors?modal=add-custom-connector> Paste this URL: `https://mcp.blotato.com/mcp`

Step-by-step video walkthrough for setting up Blotato with Claude Desktop and Cowork:

* [Claude Cowork and Desktop + Blotato MCP](https://youtu.be/mh4Z9U-oaps)

Step-by-step video walkthrough for setting up Blotato with Claude Code:

* [Claude Code + Blotato MCP](https://youtu.be/3HVH2Iuplqo)
* [The ULTIMATE Claude Code Tutorial](https://youtu.be/fYX6hHC9FhQ) (brand voice, quality gates, subagents)

## Prerequisites

1. A paid Blotato subscription
2. At least one connected social account in [Settings](https://my.blotato.com/settings)
3. For Cursor and other API-key-based clients: your Blotato API key from [Settings > API](https://my.blotato.com/settings/api)

***

## Claude.ai Web

1. In the left sidebar, click **Customize** > **Connectors**, then click the **+** button > **Add custom connector**
2. Name: `Blotato`
3. URL: `https://mcp.blotato.com/mcp`
4. Press **Connect** and approve access

You must be logged into your Blotato account in the same browser to complete the OAuth connection.

***

## Claude Desktop / Claude Cowork

1. In the left sidebar, click **Customize** > **Connectors**, then click the **+** button > **Add custom connector**
2. Name: `Blotato`
3. URL: `https://mcp.blotato.com/mcp`
4. Press **Connect** and approve access

You must be logged into your Blotato account in your default browser to complete the OAuth connection.

***

## Claude Code (Terminal)

1. Start a Claude Code session
2. Copy and paste the following command into your session:

   ```bash
   claude mcp add \
     --transport http \
     Blotato https://mcp.blotato.com/mcp
   ```
3. Let Claude apply changes
4. Once done, run `/mcp` inside the session
5. Select `Blotato > Authenticate` and approve access
6. Restart Claude Code

You must be logged into your Blotato account in your default browser to complete the OAuth connection.

***

## Other MCP Clients (Cursor, Antigravity, Codex, Replit Agent, etc.)

1. Go to [Settings > API](https://my.blotato.com/settings/api) in the Blotato app
2. Under "Other MCP Clients", click **Copy MCP Config**
3. Paste the JSON config into your app's MCP settings
4. Restart your app

The config adds the Blotato MCP server with your API key:

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

Keep the double quotes Blotato gives you and paste the full key inside them, including any trailing `=` characters. The `=` is part of your key. Do not delete it, and do not replace the double quotes with single quotes. Single quotes apply only to shells, `.env` files, and scripts, not to this JSON config. A dropped or deleted trailing `=` causes a 401 "invalid API key" error.

### Form-based setup (streamable HTTP)

Some clients, including OpenAI Codex, ask you to fill out a form instead of pasting JSON. Choose the **streamable HTTP** server type, then fill out the fields like this:

1. Go to [Settings > API](https://my.blotato.com/settings/api) in the Blotato app.
2. Click **Copy API Key** (or click **Generate API Key** first if you don't have one yet).
3. Set **URL** to `https://mcp.blotato.com/mcp`.
4. Leave **Bearer token env var** blank.
5. Under **Headers**, set the key to `blotato-api-key` and paste your API key into the **Value** field.
6. Click **Save**.

Paste the full key into the Value field, including any trailing `=` characters. A dropped `=` causes a 401 "invalid API key" error.

***

## Verify Your Connection

After setup, test the connection by asking your AI tool:

> "What social media accounts do I have connected?"

The tool calls `blotato_list_accounts` and returns your connected platforms. If you see your accounts listed, the setup is complete.

***

## 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 (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. Restart your AI tool after adding the MCP server. MCP servers load on startup.
   * **"Auth unsupported" or OAuth errors in API-key clients (Codex, Cursor, etc.):** This means the client cannot complete the OAuth browser flow. Do not use the `https://mcp.blotato.com/mcp` OAuth URL on its own. Use the API-key JSON config from the "Other MCP Clients" section above, which authenticates with the `blotato-api-key` header instead of OAuth.
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: <https://help.blotato.com/api/llm>"
5. If Blotato shows "Connected" in Claude Settings but Claude.ai returns an OAuth error when you ask it to list accounts or use any Blotato tool, your Blotato subscription is not active. Go to [Settings > API](https://my.blotato.com/settings/api) and click "Generate API Key" to activate your paid subscription. API access requires a paid plan.
6. Verify you have at least one social account connected in [Settings](https://my.blotato.com/settings).
7. If you get a JSON parsing error in your config file, validate it at [jsonlint.com](https://jsonlint.com). A common mistake is a missing comma between sections.

Video walkthrough: [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/api/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.