Connect an MCP client

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

Open the dashboard

Go to User Settings → Login & Security

Click your avatar → User Settings, then open the Login & Security tab.

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.

Copy the value

You see the token once. Store it in a password manager or an environment variable. The examples below assume PUBLISHBUDDY_TOKEN.

export PUBLISHBUDDY_TOKEN="12|aBcDeF..."

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.

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.

claude mcp add --transport http publishbuddy https://api.publishbuddy.com/mcp \
  --header "Authorization: Bearer $PUBLISHBUDDY_TOKEN"

{
  "mcpServers": {
    "publishbuddy": {
      "type": "http",
      "url": "https://api.publishbuddy.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PUBLISHBUDDY_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "publishbuddy": {
      "url": "https://api.publishbuddy.com/mcp",
      "headers": {
        "Authorization": "Bearer 12|aBcDeF..."
      }
    }
  }
}

{
  "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}"
      }
    }
  }
}

{
  "mcpServers": {
    "publishbuddy": {
      "serverUrl": "https://api.publishbuddy.com/mcp",
      "headers": {
        "Authorization": "Bearer 12|aBcDeF..."
      }
    }
  }
}

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

Where each config file lives

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.

Claude Desktop on Windows

npx must be launched through cmd on Windows:

{
  "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.

Other clients

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.

3. Verify the connection

Ask your assistant something that needs a tool:

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):

"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

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.

Tool reference

Every tool, its inputs, and its credit cost.

REST API quickstart

The same actions over plain HTTP, for pipelines and integrations.

Model Context Protocol

1. Create an API token with the MCP ability

2. Add the server to your client

3. Verify the connection

4. Choose a workspace (optional)

5. Try a real task

Troubleshooting

Next

Tool reference

REST API quickstart

​1. Create an API token with the MCP ability

​2. Add the server to your client

​3. Verify the connection

​4. Choose a workspace (optional)

​5. Try a real task

​Troubleshooting

​Next

Tool reference

REST API quickstart

1. Create an API token with the MCP ability

2. Add the server to your client

3. Verify the connection

4. Choose a workspace (optional)

5. Try a real task

Troubleshooting

Next