Connect an MCP client

You need a PublishBuddy account on Pro or Business (a 14-day trial works) and at least one connected profile. There are two ways to connect. Apps that support sign-in (OAuth), such as ChatGPT and Claude, send you to PublishBuddy to approve the connection; nothing to copy. Clients configured with a file can use an API token instead. The server URL is https://api.publishbuddy.com/mcp.

Add the server in your app

Claude (claude.ai, Claude Desktop): Settings → Connectors → Add custom connector, with the URL above.
ChatGPT: add PublishBuddy from the apps directory once it is listed there, or as a custom connector with the URL above where your workspace allows it.
Claude Code: claude mcp add --transport http publishbuddy https://api.publishbuddy.com/mcp, then run /mcp, pick publishbuddy, and choose Authenticate.
Cursor, VS Code, and other clients: add the URL with no Authorization header. The client opens the sign-in page when it first connects.

A browser page opens on app.publishbuddy.com. Sign in with your usual email and password or Google. If you are already signed in, you go straight to the next step.

Pick a workspace and allow

The page names the app, shows the website it will send you back to, and lists what it will be able to do. Pick the workspace the app should work in and click Allow. A workspace whose plan doesn’t include MCP access, or where your role can’t use AI features, can’t be picked.

Back in the app

You return to the app, connected. Try the prompt in Verify the connection.

Only click Allow for a connection you started yourself. When the page says the app runs on your own computer (a localhost address), make sure it is a program you are running, such as Claude Code or Cursor.

A signed-in app works in the workspace you picked. To use another workspace, connect the app again (most apps let you add the server twice under different names). Disconnect an app at any time under User Settings → Login & Security → Connected apps; it loses access at once. Sign-ins stay valid while the app keeps using them and expire after 90 days without use.

Use an API token

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

In the API Keys section click Generate API Key, give it a name such as claude-code, and tick the MCP (AI clients) scope. Tick the REST scopes 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="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 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 aBcDeF..."
      }
    }
  }
}

{
  "mcpServers": {
    "publishbuddy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.publishbuddy.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer 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 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 can connect to https://api.publishbuddy.com/mcp, either by signing in (the client finds the sign-in page from the server’s 401 answer, as the MCP authorization spec describes) or with an Authorization: Bearer <token> header.

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.

Choose a workspace

A signed-in app works in the workspace you picked when you allowed it. With an API token, requests run against your active workspace, the one you last used in the dashboard. If you belong to several workspaces and want a token-based 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 aBcDeF...",
  "X-Workspace-Id": "9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c"
}

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

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.
A signed-in app asks you to connect again	You disconnected it, it went unused for 90 days, or you left the workspace it was connected to.	Connect it again and pick a workspace.
The sign-in page says the request has expired or was already answered	A sign-in request lasts 30 minutes and can be answered once.	Start the connection again from the app.
A workspace can’t be picked on the sign-in page	Its plan doesn’t include MCP access, or your role there can’t use AI features.	Pick another workspace, upgrade the plan, or ask the workspace owner for AI access.
`403` “No workspace context”	Your user has no active workspace and the request sent no `X-Workspace-Id` header.	Open the dashboard once to set an active workspace, or send `X-Workspace-Id` with a workspace you belong to.
`403` “You do not have access to the requested workspace”	The `X-Workspace-Id` header names a workspace your user is not a member of. The server never falls back to another workspace.	Fix the UUID (from `GET /workspaces`) or remove the header.
`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 or upgrade.
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

Use an API token

1. Create an API token with the MCP ability

2. Add the server to your client

Verify the connection

Choose a workspace

Try a real task

Troubleshooting

Next

Tool reference

REST API quickstart

​Sign in (OAuth)

​Use an API token

​1. Create an API token with the MCP ability

​2. Add the server to your client

​Verify the connection

​Choose a workspace

​Try a real task

​Troubleshooting

​Next

Tool reference

REST API quickstart

Sign in (OAuth)

Use an API token

1. Create an API token with the MCP ability

2. Add the server to your client

Verify the connection

Choose a workspace

Try a real task

Troubleshooting

Next