> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publishbuddy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an MCP client

> Add the PublishBuddy MCP server to Claude Code, Cursor, VS Code, Windsurf, or Claude Desktop in a few minutes.

You need a PublishBuddy account on Pro or Business (a 14-day trial works) and at least one connected profile.

## 1. Create an API token with the MCP ability

<Steps>
  <Step title="Open the dashboard">
    Sign in at [app.publishbuddy.com](https://app.publishbuddy.com).
  </Step>

  <Step title="Go to User Settings → Login & Security">
    Click your avatar → **User Settings**, then open the **Login & Security** tab.
  </Step>

  <Step title="Generate a token">
    Click **Generate API token**, give it a name such as `claude-code`, and tick the **MCP (AI clients)** ability. Tick the REST abilities too only if the same token will also call the [REST API](/api-reference/introduction).
  </Step>

  <Step title="Copy the value">
    You see the token once. Store it in a password manager or an environment variable. The examples below assume `PUBLISHBUDDY_TOKEN`.
  </Step>
</Steps>

```bash theme={null}
export PUBLISHBUDDY_TOKEN="12|aBcDeF..."
```

<Warning>
  Treat the token like a password. Anyone holding it can draft and schedule posts to every profile you can access. Revoke it from the same screen if it leaks.
</Warning>

## 2. Add the server to your client

The server speaks Streamable HTTP, so clients that support remote MCP servers connect directly. Clients that only launch local (stdio) servers, such as Claude Desktop, connect through the `mcp-remote` bridge.

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport http publishbuddy https://api.publishbuddy.com/mcp \
    --header "Authorization: Bearer $PUBLISHBUDDY_TOKEN"
  ```

  ```json Claude Code (.mcp.json) theme={null}
  {
    "mcpServers": {
      "publishbuddy": {
        "type": "http",
        "url": "https://api.publishbuddy.com/mcp",
        "headers": {
          "Authorization": "Bearer ${PUBLISHBUDDY_TOKEN}"
        }
      }
    }
  }
  ```

  ```json Cursor (.cursor/mcp.json) theme={null}
  {
    "mcpServers": {
      "publishbuddy": {
        "url": "https://api.publishbuddy.com/mcp",
        "headers": {
          "Authorization": "Bearer 12|aBcDeF..."
        }
      }
    }
  }
  ```

  ```json VS Code (.vscode/mcp.json) theme={null}
  {
    "inputs": [
      {
        "type": "promptString",
        "id": "publishbuddy-token",
        "description": "PublishBuddy API token",
        "password": true
      }
    ],
    "servers": {
      "publishbuddy": {
        "type": "http",
        "url": "https://api.publishbuddy.com/mcp",
        "headers": {
          "Authorization": "Bearer ${input:publishbuddy-token}"
        }
      }
    }
  }
  ```

  ```json Windsurf (mcp_config.json) theme={null}
  {
    "mcpServers": {
      "publishbuddy": {
        "serverUrl": "https://api.publishbuddy.com/mcp",
        "headers": {
          "Authorization": "Bearer 12|aBcDeF..."
        }
      }
    }
  }
  ```

  ```json Claude Desktop (claude_desktop_config.json) theme={null}
  {
    "mcpServers": {
      "publishbuddy": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://api.publishbuddy.com/mcp",
          "--header",
          "Authorization:${AUTH_HEADER}"
        ],
        "env": {
          "AUTH_HEADER": "Bearer 12|aBcDeF..."
        }
      }
    }
  }
  ```
</CodeGroup>

<AccordionGroup>
  <Accordion title="Where each config file lives" icon="folder">
    * **Claude Code**: the CLI command stores the server in your user config. A project-level `.mcp.json` in the repo root is shared with anyone who clones it, so keep the token in an environment variable there.
    * **Cursor**: `.cursor/mcp.json` in a project, or `~/.cursor/mcp.json` for every project.
    * **VS Code**: `.vscode/mcp.json` in a workspace. The `inputs` block prompts for the token once and stores it securely.
    * **Windsurf**: `~/.codeium/windsurf/mcp_config.json`.
    * **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Restart the app after editing.
  </Accordion>

  <Accordion title="Claude Desktop on Windows" icon="windows">
    `npx` must be launched through `cmd` on Windows:

    ```json theme={null}
    {
      "mcpServers": {
        "publishbuddy": {
          "command": "cmd",
          "args": [
            "/c", "npx", "-y", "mcp-remote",
            "https://api.publishbuddy.com/mcp",
            "--header", "Authorization:${AUTH_HEADER}"
          ],
          "env": { "AUTH_HEADER": "Bearer 12|aBcDeF..." }
        }
      }
    }
    ```

    The header is written as `Authorization:${AUTH_HEADER}` without a space on purpose. Claude Desktop splits arguments on spaces, so the space lives inside the environment variable instead.
  </Accordion>

  <Accordion title="Other clients" icon="plug">
    Any client that supports remote MCP servers over Streamable HTTP with custom headers can connect: set the URL to `https://api.publishbuddy.com/mcp` and add an `Authorization: Bearer <token>` header. Clients that only support OAuth sign-in for remote servers, such as ChatGPT connectors and Claude.ai web connectors, are not supported yet.
  </Accordion>
</AccordionGroup>

## 3. Verify the connection

Ask your assistant something that needs a tool:

```text theme={null}
List my PublishBuddy profiles.
```

You should see it call `list_profiles` and reply with your connected accounts. Most clients ask for permission before running a tool the first time. Approve it, and optionally allow the read-only tools permanently so you are only asked when something changes.

## 4. Choose a workspace (optional)

Requests run against your **active workspace**, the one you last used in the dashboard. If you belong to several workspaces and want a client pinned to one of them, add an `X-Workspace-Id` header with that workspace's UUID (from `GET /workspaces` on the REST API, or from the workspace switcher URL in the dashboard):

```json theme={null}
"headers": {
  "Authorization": "Bearer 12|aBcDeF...",
  "X-Workspace-Id": "9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c"
}
```

Configure the server twice under different names to switch between workspaces from the same client.

## 5. Try a real task

```text theme={null}
Show me my top 5 posts on Instagram for the last 30 days, then draft a post in the same
style for Thursday at 7 pm and schedule it. Ask me before scheduling.
```

The assistant will call `get_top_posts`, then `create_post` (which makes a draft), then `schedule_post`. Creating a post never publishes anything on its own; scheduling or queueing is always a separate call, and your client asks before each one unless you have allowed it.

## Troubleshooting

| Symptom                                                                    | Cause                                                                                       | Fix                                                                                                          |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Server shows as disconnected, `401` in logs                                | Token is wrong, revoked, or the header is missing.                                          | Re-copy the token. In Claude Desktop, check the `env` block is present.                                      |
| `403` "No workspace context"                                               | Your user has no active workspace, or the header names a workspace you are not a member of. | Open the dashboard once to set an active workspace, or send `X-Workspace-Id` with a workspace you belong to. |
| `403` "The API token is missing a required ability for this endpoint: mcp" | The token was created without the **MCP (AI clients)** ability.                             | Abilities cannot be added to an existing token. Generate a new one with it ticked.                           |
| `402` on connect                                                           | The workspace's plan does not include MCP access.                                           | Upgrade to Pro or Business.                                                                                  |
| `402` on `generate_image` or `edit_image`                                  | Not enough AI credits for the call.                                                         | Wait for the monthly reset, upgrade, or configure a workspace AI provider key (BYOK).                        |
| Tool works in the dashboard but not here                                   | Your dashboard role limits the action (for example, draft-only members cannot schedule).    | Ask the workspace owner to adjust your role. MCP never grants more than the dashboard does.                  |
| `429`                                                                      | More than 60 requests in a minute.                                                          | Wait for `Retry-After` seconds.                                                                              |

## Next

<CardGroup cols={2}>
  <Card title="Tool reference" icon="screwdriver-wrench" href="/mcp-server/tools">
    Every tool, its inputs, and its credit cost.
  </Card>

  <Card title="REST API quickstart" icon="terminal" href="/quickstart">
    The same actions over plain HTTP, for pipelines and integrations.
  </Card>
</CardGroup>