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#

ItemValue
Server URLhttps://api.pilotdeck.co/mcp
TransportStreamable 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.
AuthenticationAuthorization: Bearer <token>. The token is a personal token from Settings or one issued through OAuth sign-in. Both start with pdk_.
Scope of accessOne user, one site. A token cannot reach another site or another account.
PlansEvery active plan. A workspace with no active plan gets 402.
CapabilitiesTools 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.

ToolReturnsInputs
get_siteThe site's domain, publish mode, draft handling and today's summary of what PilotDeck is doing and what needs the owner.None
get_planThe 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_stateWhere the plan stands this week: counts by status, the current week, what moved.None
get_topicOne 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_backlogEvery researched topic with demand, difficulty, beatable results and whether it passed the checks.q (filter), limit (1 to 200)
get_briefThe brief for a plan item: angle, outline, questions to answer, page-one evidence. Returned whole.item_id
get_brand_profileAudience, services, service areas, exclusions, competitor brands and voice (tone, dos and don'ts, banned words). Returned whole.None
get_verified_factsThe 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_contentJudges 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_draftsEvery item in the content pipeline with its stage and itemId.review_statuses (pending, inprogress, block, done), start_date, end_date (YYYY-MM-DD)
get_draftThe current version of a draft: title, markdown, meta description, hero image, review state. Returned whole.item_id
get_ai_visibilityThe tracking state and, for each tracked question, whether AI answers name the brand. Paged.page, limit (1 to 50)
get_ai_answerWhat each AI answer said for one tracked question, the brands it named and the sources it cited.question_id
get_competitorsCompetitors found on page one, the verdict on each, and whether the review is still open.None
get_social_postsThe social post queue: per platform, the kind of post, its copy and status.None
get_engine_activityWhat PilotDeck is doing for the site right now and what is waiting on the owner.None
get_usageThis 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 of markdown, title, meta_description; optional change_note for 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 (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.

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

Scopes#

ScopeShown to the user asTools
readRead the plan with its reasons, briefs, verified facts, drafts, AI visibility, competitors and usageAll read tools. Always included.
content:writeEdit a draft's text and save it back (no regeneration from an agent)update_draft
profile:writeEdit the brand profile: audience, services, exclusions, competitor brands, voiceupdate_brand_profile
visibility:writeAdd or change the tracked AI questions (tracking itself is started in Pilotdeck)add_ai_question, update_ai_question
competitors:writeAdd or change the competitors to researchconfirm_competitors
social:writeGive feedback on social postssocial_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_draft returns can be sent back to update_draft.

Limits#

LimitValue
Tool calls per token60 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 batch20
Request body1 MB
Draft markdown200,000 characters for check_content and update_draft
Active tokens per user20, counting OAuth connections
Token name1 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.

EndpointPurpose
/.well-known/oauth-protected-resourceProtected resource metadata (RFC 9728). Also served at /.well-known/oauth-protected-resource/mcp.
/.well-known/oauth-authorization-serverAuthorization server metadata (RFC 8414). Also served with /mcp appended.
POST /oauth/registerDynamic client registration (RFC 7591). Public clients only.
GET /oauth/authorizeStarts sign-in and sends the user to the PilotDeck consent page, where they pick a site and click Allow.
POST /oauth/tokenExchanges the code, or a refresh token, for tokens.
POST /oauth/revokeRevokes an access or refresh token (RFC 7009). Always answers 200.

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

RuleValue
Grant typesauthorization_code with PKCE (S256 only), and refresh_token
Client authenticationNone (token_endpoint_auth_method none). Do not set a client secret.
Redirect URIshttps, or http on localhost, 127.0.0.1 or [::1], where any port is accepted. Up to 5, each under 512 characters.
Consent pageValid for 10 minutes
Authorization codeValid for 5 minutes, single use
Access token30 days
Refresh token90 days. Each refresh issues a new access and refresh token and revokes the old pair. Scopes carry over unchanged.
Registration and sign-in starts10 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).

StatusCodeMeaning
401TOKEN_REQUIREDNo Authorization: Bearer pdk_... header, or the value is not a PilotDeck token.
401TOKEN_INVALIDThe token is unknown or revoked, or the account is not active.
401TOKEN_EXPIREDThe token has passed its expiry. OAuth clients refresh; for a personal token, create a new one.
402PLAN_REQUIREDThe workspace has no active plan: its subscription was cancelled, a payment failed or its trial ended.
403FORBIDDEN_SITEThe token's site is archived or inactive, or access was revoked.
400BATCH_TOO_LARGEMore than 20 calls in one batch.
405METHOD_NOT_ALLOWEDGET or DELETE on /mcp. Use POST.
429RATE_LIMITEDMore than 60 tool calls in a minute for this token.
503RATE_LIMIT_UNAVAILABLEUsage 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:

CodeMeaning
scope_requiredThe token lacks the scope this tool needs.
invalid_inputAn input is not valid, for example a list that would empty a brand profile field.
not_foundThe item, question or post does not exist on this site.
plan_limit_reachedA plan quota is used up for this period.
nothing_to_saveupdate_draft was called with no field to change.
review_closedconfirm_competitors was called after the competitor review closed.
brief_not_startedThe brief is not written yet. It is written when the topic reaches the front of the plan.
brief_queued, brief_generatingThe brief is being written. Check back in a few minutes.
brief_failed, brief_rejectedNo brief will come for this topic. Pick another one.
engine_unavailable, errorPilotDeck 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.