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

# MCP server

> Connect Claude Code, Cursor, or any MCP client to your PublishBuddy workspace and let it read analytics, draft posts, and schedule them.

PublishBuddy hosts a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. MCP is the open standard AI assistants use to call tools inside other applications. Connect an MCP client to your workspace and it can list your profiles, read analytics, create and schedule posts, and generate images, using the same tools that power the AI Agent inside the dashboard.

<Info>
  **Endpoint** — `https://api.publishbuddy.com/mcp`
  **Transport** — Streamable HTTP (JSON-RPC over `POST`)
  **Auth** — `Authorization: Bearer <your-token>`, using an API token with the `mcp` ability
  **Plans** — Pro and Business
</Info>

<CardGroup cols={2}>
  <Card title="Connect a client" icon="rocket" href="/mcp-server/connect">
    Copy-paste configuration for Claude Code, Cursor, VS Code, Windsurf, and Claude Desktop.
  </Card>

  <Card title="Tool reference" icon="screwdriver-wrench" href="/mcp-server/tools">
    Every tool the server exposes, what it needs, and what it costs in AI credits.
  </Card>
</CardGroup>

## What an MCP client can do

<Columns cols={2}>
  <Card title="Read analytics" icon="chart-line">
    Engagement summaries, top and bottom posts, best times to post, and hashtag performance for any profile or the whole workspace.
  </Card>

  <Card title="Draft and schedule" icon="calendar">
    Create draft posts with media from the library, then schedule them for a date and time or add them to a profile's queue.
  </Card>

  <Card title="Generate images" icon="image">
    Generate or edit an AI image for a post. Finished images land in the media library, ready to attach.
  </Card>

  <Card title="Understand what works" icon="eye">
    Explain why a post performed, search the library by visual features, and build a creative brief from reference posts.
  </Card>
</Columns>

## How it fits together

```text theme={null}
Your MCP client ──▶ POST https://api.publishbuddy.com/mcp ──▶ your workspace
(Claude Code, Cursor, ...)      Bearer token + mcp ability         profiles, posts, analytics
```

* **One token, one user.** The token identifies you. Every tool runs with the permissions your user has in the dashboard, so a member who can only draft in the app can only draft over MCP too.
* **One workspace per request.** Requests run against your active workspace, the one you last used in the dashboard. To target a different workspace, send an `X-Workspace-Id` header with the workspace UUID from `GET /workspaces`.
* **Same server as the in-app AI Agent.** The assistant in the dashboard is an MCP client of this server. Connecting your own client gives it the same tools; it does not add a second set of permissions.

<Note>
  The **Copy page** menu on these docs also offers an MCP option. That is the docs site's own search server hosted by Mintlify, not the PublishBuddy workspace server described here.
</Note>

## Credits

Most tools are free of AI credits. The ones that call an AI model to produce something are charged against the workspace's monthly credits, the same pool the in-app AI Agent uses (500 on Pro, 2,500 on Business). Workspaces with their own AI provider key configured (BYOK) are never charged.

| Tool             | Credits per call |
| ---------------- | ---------------- |
| `generate_image` | 17               |
| `edit_image`     | 17               |
| `get_top_posts`  | 1                |
| Every other tool | 0                |

A tool that would exceed the remaining balance returns a `402` before it runs, with the cost and the balance in the message.

## Rate limits

The MCP endpoint is limited to **60 requests per minute** per user. Exceeding it returns `429` with a `Retry-After` header. Each tool call is one request; an assistant working through a multi-step task stays well inside this.

## Errors you may see

| Status | Meaning                                                                                                                    | What to do                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `401`  | The token is missing, malformed, or revoked.                                                                               | Generate a new token in **User Settings → Login & Security** and update your client config.           |
| `402`  | The workspace's plan does not include MCP access, or the workspace has run out of AI credits for a credit-charging tool.   | Upgrade the plan, top up credits, or configure a workspace AI key.                                    |
| `403`  | No workspace context, the token lacks the `mcp` ability, or your user is not allowed to use AI features in this workspace. | Send `X-Workspace-Id`, mint a token with the `mcp` ability, or ask the workspace owner for AI access. |
| `429`  | Rate limit hit.                                                                                                            | Wait for `Retry-After` seconds.                                                                       |

## MCP or the REST API?

Use the [REST API](/api-reference/introduction) when code is doing the work: a pipeline that publishes from your CMS, a nightly analytics sync, or a client portal. Use MCP when a person is doing the work through an assistant: planning a week of content in one conversation, pulling numbers into a report you are already writing, or publishing a changelog post from your editor. Both use the same API tokens and respect the same plan.