work with PilotDeck in a chat
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.
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 or Connect an AI agent with an MCP token. This page is the technical reference behind both.
Tools that read OpenAPI can use the OpenAPI description of the server and its sign-in endpoints. MCP clients do not need it. Agents reading this site can start at /agents.txt or /llms.txt.
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.
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 |
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.
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 ofmarkdown,title,meta_description; optionalchange_notefor the version history
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
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
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
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)
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(upordown),reasons(up to 8),note,edited_text
Question category is one of how_to, cost, best, use_case, comparison or local_hire.
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.
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_draftreturns can be sent back toupdate_draft.
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 |
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 |
Errors#
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. |
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. |
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
Need help? Contact support.