# PilotDeck MCP server reference

> Every tool, ability, limit and error code of the PilotDeck MCP server, plus how sign-in and tokens work, for people building or debugging an AI agent.

PilotDeck is a growth platform for SEO, GEO and AI visibility. It researches, writes and publishes content for a website, and drafts wait for approval by default.

Published 2026-11-05. [AI assistants](https://docs.pilotdeck.co/ai-assistants). Web page: https://docs.pilotdeck.co/ai-assistants/mcp-server

<a id="intro"></a>
## About the MCP server

PilotDeck runs a Model Context Protocol (MCP) server so AI assistants and agents can work with one PilotDeck site: read the content plan and the reasons behind it, briefs, drafts, verified facts and AI visibility, check a draft against PilotDeck's rules, and make a small set of reviewed changes. It gives an agent PilotDeck's judgment about a site, not raw keyword or ranking data.

To connect, follow [Connect Claude to PilotDeck](https://docs.pilotdeck.co/ai-assistants/claude) or [Connect an AI agent with an MCP token](https://docs.pilotdeck.co/ai-assistants/mcp-token). This page is the technical reference behind both.

Tools that read OpenAPI can use [the OpenAPI description](https://docs.pilotdeck.co/openapi.json) of the server and its sign-in endpoints. MCP clients do not need it. Agents reading this site can start at [/agents.txt](https://docs.pilotdeck.co/agents.txt) or [/llms.txt](https://docs.pilotdeck.co/llms.txt).

<a id="connection"></a>
## Connection details

| Item | Value |
| --- | --- |
| Server URL | `https://api.pilotdeck.co/mcp` |
| Transport | Streamable HTTP. Each request is a `POST` with a JSON-RPC 2.0 body, answered with JSON. The server keeps no session, so `GET` and `DELETE` answer `405`. |
| Authentication | `Authorization: Bearer <token>`. The token is a personal token from Settings or one issued through OAuth sign-in. Both start with `pdk_`. |
| Scope of access | One user, one site. A token cannot reach another site or another account. |
| Plans | Every active plan. A workspace with no active plan gets `402`. |
| Capabilities | Tools only. The server does not offer MCP resources or prompts. |

A request without a valid token gets `401` with a `WWW-Authenticate` header that points to the OAuth metadata, so clients that support MCP authorization start the sign-in flow on their own.

<a id="read-tools"></a>
## Read tools

These tools never change anything and never start paid work. Every token can use them.

| Tool | Returns | Inputs |
| --- | --- | --- |
| `get_site` | The site's domain, publish mode, draft handling and today's summary of what PilotDeck is doing and what needs the owner. | None |
| `get_plan` | The content plan: every topic with its tier (ready, stretch or foundation), the reason it is on the plan, funnel stage, demand, week and status. | `scope` (`current` or `all`), `lane`, `category`, all optional |
| `get_plan_state` | Where the plan stands this week: counts by status, the current week, what moved. | None |
| `get_topic` | One plan item in depth: who holds page one and with what kind of page, the questions people ask, the brief if written, the AI questions it answers, draft status. | `item_id` |
| `get_backlog` | Every researched topic with demand, difficulty, beatable results and whether it passed the checks. | `q` (filter), `limit` (1 to 200) |
| `get_brief` | The brief for a plan item: angle, outline, questions to answer, page-one evidence. Returned whole. | `item_id` |
| `get_brand_profile` | Audience, services, service areas, exclusions, competitor brands and voice (tone, dos and don'ts, banned words). Returned whole. | None |
| `get_verified_facts` | The only claims a page may make about the business, such as offerings, prices and proof, each with the page it was read from. | `q` (filter), `limit` (1 to 200) |
| `check_content` | Judges a draft written anywhere by the rules PilotDeck's writer must pass, including banned words and price, trial, free plan and guarantee claims against verified facts. Returns blocking issues and advisories. Rule based, fast and free. | `markdown` (50 to 200,000 characters, H1 first), `title`, `head` (the primary keyword, turns on keyword checks), `meta_description` |
| `list_drafts` | Every item in the content pipeline with its stage and `itemId`. | `review_statuses` (`pending`, `inprogress`, `block`, `done`), `start_date`, `end_date` (YYYY-MM-DD) |
| `get_draft` | The current version of a draft: title, markdown, meta description, hero image, review state. Returned whole. | `item_id` |
| `get_ai_visibility` | The tracking state and, for each tracked question, whether AI answers name the brand. Paged. | `page`, `limit` (1 to 50) |
| `get_ai_answer` | What each AI answer said for one tracked question, the brands it named and the sources it cited. | `question_id` |
| `get_competitors` | Competitors found on page one, the verdict on each, and whether the review is still open. | None |
| `get_social_posts` | The social post queue: per platform, the kind of post, its copy and status. | None |
| `get_engine_activity` | What PilotDeck is doing for the site right now and what is waiting on the owner. | None |
| `get_usage` | This billing period's meters: content pieces, social ideas, tracked AI questions, used and limit. | None |

<a id="write-tools"></a>
## Write tools

Each write tool needs its own scope and goes through the same checks, quotas and history as the same change in the app. Tools that replace data are marked as destructive, a hint that tells clients to confirm with the user first.

<a id="update-draft"></a>
### `update_draft`

Saves an edited draft as a new version. Fields left out are kept. `markdown`, when sent, replaces the whole body. Never regenerates. Not allowed on published drafts.

- Scope: `content:write`
- Effect: replaces stored data
- Inputs: `item_id`, and at least one of `markdown`, `title`, `meta_description`; optional `change_note` for the version history

<a id="update-brand-profile"></a>
### `update_brand_profile`

Changes the fields sent. A list replaces the stored list whole and an empty list is refused. Inside `voice`, only the keys sent change.

- Scope: `profile:write`
- Effect: replaces stored data
- Inputs: `icp`, `services`, `service_areas`, `exclusions`, `competitor_brands` (1 to 60 entries each), `voice`

<a id="add-ai-question"></a>
### `add_ai_question`

Adds a tracked question. It is always saved. It may come back `tracked: false` with a `reason` (`plan_limit` or `not_selected`) when the plan's checked slots are taken.

- Scope: `visibility:write`
- Effect: adds only
- Inputs: `question` (8 to 240 characters), `category`

<a id="update-ai-question"></a>
### `update_ai_question`

Rewrites a question's text or type. New text clears the answers recorded for the old wording.

- Scope: `visibility:write`
- Effect: replaces stored data
- Inputs: `question_id`, `question`, `category`

<a id="confirm-competitors"></a>
### `confirm_competitors`

While the competitor review is open, sets the full list to keep. Unlisted candidates are dismissed, the review closes and research of the kept ones starts, which uses the plan.

- Scope: `competitors:write`
- Effect: replaces stored data
- Inputs: `domains` (up to 20)

<a id="social-feedback"></a>
### `social_feedback`

Records a thumbs up or down on a social post, with reasons, a note and the copy actually posted.

- Scope: `social:write`
- Effect: adds only
- Inputs: `post_id`, `verdict` (`up` or `down`), `reasons` (up to 8), `note`, `edited_text`

Question `category` is one of `how_to`, `cost`, `best`, `use_case`, `comparison` or `local_hire`.

> [!TIP]
> No tool publishes, approves, deletes, changes billing, the publish mode, draft handling, connections or tokens, fetches a URL, or reaches another site.

<a id="scopes"></a>
## Scopes

| Scope | Shown to the user as | Tools |
| --- | --- | --- |
| `read` | Read the plan with its reasons, briefs, verified facts, drafts, AI visibility, competitors and usage | All read tools. Always included. |
| `content:write` | Edit a draft's text and save it back (no regeneration from an agent) | `update_draft` |
| `profile:write` | Edit the brand profile: audience, services, exclusions, competitor brands, voice | `update_brand_profile` |
| `visibility:write` | Add or change the tracked AI questions (tracking itself is started in Pilotdeck) | `add_ai_question`, `update_ai_question` |
| `competitors:write` | Add or change the competitors to research | `confirm_competitors` |
| `social:write` | Give feedback on social posts | `social_feedback` |

Tokens created in Settings get every scope. An OAuth client gets exactly the scopes it asks for, with `read` always added. A client that asks for none, or only for scopes PilotDeck does not know, gets all six. A tool called without its scope returns the error `scope_required`.

<a id="results"></a>
## How results look

- Every result starts with a one-line summary, followed by the data as JSON. The JSON is also sent as `structuredContent`.
- The JSON is labelled as data from PilotDeck, not instructions, so text quoted from third parties, such as AI answers, cannot pass as commands.
- List results are kept to about 30,000 characters. When a list is shortened, the result says so and how to narrow the call.
- Single documents, such as a draft, a brief or the brand profile, are returned whole or not at all, never cut. Read and write stay symmetric: what `get_draft` returns can be sent back to `update_draft`.

<a id="limits"></a>
## Limits

| Limit | Value |
| --- | --- |
| Tool calls per token | 60 a minute. Every call inside a batch counts. Requests that call no tool, such as listing tools, are refused only once the minute's calls are used up. |
| Calls in one JSON-RPC batch | 20 |
| Request body | 1 MB |
| Draft markdown | 200,000 characters for `check_content` and `update_draft` |
| Active tokens per user | 20, counting OAuth connections |
| Token name | 1 to 60 characters |

<a id="oauth"></a>
## OAuth sign-in

Clients such as Claude connect with OAuth 2.1 instead of a pasted token. The access token they receive works exactly like a personal token and appears in the same list in Settings.

| Endpoint | Purpose |
| --- | --- |
| `/.well-known/oauth-protected-resource` | Protected resource metadata (RFC 9728). Also served at `/.well-known/oauth-protected-resource/mcp`. |
| `/.well-known/oauth-authorization-server` | Authorization server metadata (RFC 8414). Also served with `/mcp` appended. |
| `POST /oauth/register` | Dynamic client registration (RFC 7591). Public clients only. |
| `GET /oauth/authorize` | Starts sign-in and sends the user to the PilotDeck consent page, where they pick a site and click Allow. |
| `POST /oauth/token` | Exchanges the code, or a refresh token, for tokens. |
| `POST /oauth/revoke` | Revokes an access or refresh token (RFC 7009). Always answers `200`. |

All endpoints live on `https://api.pilotdeck.co`.

| Rule | Value |
| --- | --- |
| Grant types | `authorization_code` with PKCE (`S256` only), and `refresh_token` |
| Client authentication | None (`token_endpoint_auth_method` `none`). Do not set a client secret. |
| Redirect URIs | https, or http on `localhost`, `127.0.0.1` or `[::1]`, where any port is accepted. Up to 5, each under 512 characters. |
| Consent page | Valid for 10 minutes |
| Authorization code | Valid for 5 minutes, single use |
| Access token | 30 days |
| Refresh token | 90 days. Each refresh issues a new access and refresh token and revokes the old pair. Scopes carry over unchanged. |
| Registration and sign-in starts | 10 registrations and 30 sign-in starts per 10 minutes per IP address, then `429` with `Retry-After` |

<a id="errors"></a>
## Errors

<a id="http-errors"></a>
### Request errors

Refused requests answer with an HTTP status and a JSON body with `code`, `error` (technical text) and `userMessage` (a sentence you can show a person).

| Status | Code | Meaning |
| --- | --- | --- |
| `401` | `TOKEN_REQUIRED` | No `Authorization: Bearer pdk_...` header, or the value is not a PilotDeck token. |
| `401` | `TOKEN_INVALID` | The token is unknown or revoked, or the account is not active. |
| `401` | `TOKEN_EXPIRED` | The token has passed its expiry. OAuth clients refresh; for a personal token, create a new one. |
| `402` | `PLAN_REQUIRED` | The workspace has no active plan: its subscription was cancelled, a payment failed or its trial ended. |
| `403` | `FORBIDDEN_SITE` | The token's site is archived or inactive, or access was revoked. |
| `400` | `BATCH_TOO_LARGE` | More than 20 calls in one batch. |
| `405` | `METHOD_NOT_ALLOWED` | `GET` or `DELETE` on `/mcp`. Use `POST`. |
| `429` | `RATE_LIMITED` | More than 60 tool calls in a minute for this token. |
| `503` | `RATE_LIMIT_UNAVAILABLE` | Usage could not be checked, so the call was refused. Retry shortly. |

<a id="tool-errors"></a>
### Tool errors

A tool that cannot complete returns a normal JSON-RPC result with `isError: true`. The text starts with a code, and `structuredContent` carries `error` (the code) and `message`. Common codes:

| Code | Meaning |
| --- | --- |
| `scope_required` | The token lacks the scope this tool needs. |
| `invalid_input` | An input is not valid, for example a list that would empty a brand profile field. |
| `not_found` | The item, question or post does not exist on this site. |
| `plan_limit_reached` | A plan quota is used up for this period. |
| `nothing_to_save` | `update_draft` was called with no field to change. |
| `review_closed` | `confirm_competitors` was called after the competitor review closed. |
| `brief_not_started` | The brief is not written yet. It is written when the topic reaches the front of the plan. |
| `brief_queued`, `brief_generating` | The brief is being written. Check back in a few minutes. |
| `brief_failed`, `brief_rejected` | No brief will come for this topic. Pick another one. |
| `engine_unavailable`, `error` | PilotDeck could not complete the call. Retry shortly. |

<a id="security"></a>
## Security

- PilotDeck stores only a fingerprint of each token, never the token itself, and shows the full token once.
- Every request is checked against the token's user, site and plan, with the same site isolation as the app.
- Every tool call is recorded with the tool, the result and how long it took.
- Revoking a token, in Settings or through `/oauth/revoke`, stops it at once. Revoking an OAuth connection also revokes its refresh token.

## Official documentation

- [What is the Model Context Protocol](https://modelcontextprotocol.io/introduction)
- [MCP authorization specification](https://modelcontextprotocol.io/specification/latest/basic/authorization)

## Related guides

- [Connect Claude to PilotDeck](https://docs.pilotdeck.co/ai-assistants/claude.md): Sign in with PilotDeck
- [Connect an AI agent with an MCP token](https://docs.pilotdeck.co/ai-assistants/mcp-token.md): Personal MCP token

Need help? [Contact support](mailto:support@pilotdeck.co).
