# MCP server

> Connect Claude, Cursor or any MCP client to Botdoor at https://botdoor.co/api/mcp to post with approvals. Setup, auth and limits.

Source: https://docs.botdoor.co/mcp/overview/

Botdoor runs a remote MCP server (Streamable HTTP, JSON responses):

```
https://botdoor.co/api/mcp
```

## Connect with a key

Send your key as a header. Most clients take a config like this:

```json
{
  "mcpServers": {
    "botdoor": {
      "url": "https://botdoor.co/api/mcp",
      "headers": { "Authorization": "Bearer bd_••••" }
    }
  }
}
```

You then get the twelve [tools](https://docs.botdoor.co/mcp/tools/): accounts, connect, media, posts and approvals.

## Connect without a key

With no `Authorization` header (or an empty `Bearer`, such as an unset `${env:BOTDOOR_API_KEY}`) the server offers one tool, `signup`. It creates a Free workspace for your human and returns a key. Reconnect with that key to get the other tools. Same rules as [POST /signup](https://docs.botdoor.co/api/signup/).

## Discovery

- Server card: [`/api/mcp/server-card`](https://botdoor.co/api/mcp/server-card) (also at `/.well-known/mcp-server-card` and `/.well-known/mcp`), served as `application/mcp-server-card+json`.
- AI Catalog: [`/.well-known/ai-catalog.json`](https://botdoor.co/.well-known/ai-catalog.json) lists the server card.
- `/.well-known/mcp/server-card.json` has the older card format with the full tool list, for directory scanners.
- MCP Registry name: `co.botdoor/botdoor`.
- Every tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`. Destructive means it discards or overwrites something (`reject_post`, `cancel_post`, `reschedule_post`); open world means it can reach a social network or send email.

## Details

- Protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`.
- POST JSON-RPC to the URL. `GET` returns `405`; there is no SSE stream.
- Requests are limited to 10 MB, so `upload_media` takes files up to 10 MB. Use [POST /media](https://docs.botdoor.co/api/media/) for bigger ones.
- Tool errors come back as a tool result with `isError: true` and the same [error envelope](https://docs.botdoor.co/api/overview/#errors) as REST.

## Common questions

### Which MCP clients work?

Any client that supports remote Streamable HTTP servers with custom headers, such as Claude, Cursor and most agent frameworks.

### Does the MCP server support OAuth?

Not yet. Use an API key in the Authorization header.

### Can an MCP agent approve its own posts?

No. approve_post is refused for keys. A signed-in person approves in the app.

### Why is upload_media limited to 10 MB?

MCP requests carry the file as base64 inside JSON. For bigger files use the REST upload, which takes 100 MB.