When to use a token#

PilotDeck runs an MCP server, the open standard AI agents use to connect to other apps. There are two ways to connect to it:

Sign-inMCP token
Best forClaude on the web, desktop or mobile, and Claude CodeCursor, scripts and any MCP client that can send a header
How you connectSign in to PilotDeck and click AllowCreate a token in Settings and paste it into the agent
ExpiryRenewed by the app while in useDoes not expire until you revoke it
GuideConnect Claude to PilotDeckThis page

Both give the agent the same abilities on one site, and both show up in the same list in PilotDeck, where you can revoke them.

Before you start#

You needDetails
An active PilotDeck planEvery plan includes AI agent access. An account without an active plan sees "Your PilotDeck account doesn't have an active plan, so AI agents can't connect." when it tries to create a token.
Permission to manage settingsThe AI agents (MCP) section shows only to people who can manage the account's settings, such as the owner.
The right site selectedA token works for the site that is selected in the site switcher when you create it. Switch site first if needed.
An MCP clientAny client that supports remote MCP servers over Streamable HTTP and lets you set an Authorization header, for example Claude Code or Cursor.

Overview#

  1. 1Open Settings > Integrations in PilotDeckYou
  2. 2Create a token under AI agents (MCP)You
  3. 3Copy the token or the configYou
  4. 4Add it to your agentYou
  5. 5The agent can now work with that siteVerify
1

Open AI agents in Settings#

You

In PilotDeck, open Settings > Integrations and scroll to AI agents (MCP). The section shows the server address your agent connects to:

Server address
https://api.pilotdeck.co/mcp
Settings > Integrations > AI agents (MCP). Personal tokens and sign-in connections share one list. Sample values.
2

Create a token#

You

Click New token. The window names the site the token is for. Give the token a name of up to 60 characters that says where it will be used, for example "Cursor, work laptop", so you can recognise it later. The window lists What the agent can do. Click Create token.

The window names the site and lists what the agent can do. Sample values.
Copy it now. The next window, Copy your token now, is the only time the token is shown. PilotDeck keeps only a fingerprint of it and cannot show it again. If you lose it, revoke it and create a new one.
Copy your token now. The token is hidden here; you see the real one once.

A token starts with pdk_. Treat it like a password: anyone who has it can work with your site as you.

3

Add the token to your agent#

You

The window gives you a ready config to copy. Use the option that matches your agent.

Claude Code

Run this in a terminal, with your token in place of <your-token>:

Terminal
claude mcp add --transport http pilotdeck https://api.pilotdeck.co/mcp --header "Authorization: Bearer <your-token>"

Prefer not to handle a token? Leave out the --header part, then run /mcp inside Claude Code and choose to authenticate PilotDeck. Your browser opens the PilotDeck sign-in page, where you pick the site and click Allow, as in Connect Claude to PilotDeck.

Cursor and other config file clients

Paste the copied config into the client's MCP config file, for example mcp.json in Cursor:

mcp.json
{
  "mcpServers": {
    "pilotdeck": {
      "url": "https://api.pilotdeck.co/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Any other MCP client

SettingValue
Server URLhttps://api.pilotdeck.co/mcp
TransportStreamable HTTP (sometimes listed as HTTP). Not stdio, not the older SSE transport.
HeaderAuthorization: Bearer <your-token>

Claude Desktop and Claude on the web

These connect with sign-in, not a token. Follow Connect Claude to PilotDeck.

4

Check it works#

Verify

Ask your agent "which PilotDeck site are you connected to?", then "what should this site write next?". It answers from your PilotDeck data. Back in Settings, the token shows a last used time.

What the agent can do#

  • Read the plan with its reasons, briefs, verified facts, drafts, AI visibility, competitors and usage
  • Edit a draft's text and save it back (no regeneration from an agent)
  • Edit the brand profile: audience, services, exclusions, competitor brands, voice
  • Add or change the tracked AI questions (tracking itself is started in Pilotdeck)
  • Add or change the competitors to research
  • Give feedback on social posts

A token you create in Settings always gets all of these. The MCP server reference lists every tool, its inputs and what it changes.

An agent can never publish to your website, approve or delete content, or reach your other sites. Edited drafts still wait for your review in PilotDeck.

Manage and revoke tokens#

  • Every active token is listed under AI agents (MCP) with its name, the last four characters of the token, the site if it is not the one you have selected, and when it was last used.
  • Connections made by sign-in, such as Claude, appear in the same list with the app's name and an expiry date.
  • Tokens you create here do not expire. Revoke the ones you no longer use.
  • Click Revoke, then Revoke token. Any agent using it stops straight away, even in the middle of a task. This cannot be undone. Click Keep it to back out.
  • You can have up to 20 active tokens, counting sign-in connections. Revoke one to create another.

Keep tokens safe#

  • Create one token per tool and machine. If one leaks, you revoke it without breaking the others.
  • Keep config files that hold a token out of shared folders and code repositories.
  • Do not share a token with a teammate. Each person should sign in and create their own.
  • If a token may have leaked, revoke it at once and create a new one.
  • Agents can be misled by instructions hidden in text they read elsewhere. Review what your agent plans to change before you approve it.

Troubleshooting#

When something fails, most clients show the HTTP status and the message from PilotDeck.

Status and messageWhat to do
401 "An API token is required"The header is missing or not in the form Authorization: Bearer pdk_.... Check for a missing Bearer, extra quotes or a cut-off token.
401 "This token is not valid or was revoked"The token was revoked, mistyped, or the account is no longer active. Create a new token.
402 "AI agent access (MCP) needs an active PilotDeck plan."The subscription was cancelled, a payment failed or the trial ended. The same token works again once the plan is active. Contact support if you think this is wrong.
429 "Rate limit: 60 calls per minute per token"Wait a minute. Each tool call counts, including every call inside one batch.
400 "A batch may hold at most 20 calls"The client sent too many calls in one request. Ask it to send fewer at a time.
405 on a GET requestPilotDeck takes POST requests only. Set the client's transport to Streamable HTTP.
A tool answers scope_requiredThe connection was made without that ability. Create a token in Settings, which always has every ability.

Common questions#

Can I use one token for two sites?

No. Each token covers one site. Create a separate token for each site, with the right site selected.

Can I choose which abilities a token has?

Not in Settings. Every token created there gets all the abilities listed above. Revoke it whenever you want to stop access.

Can I set an expiry date?

Not in Settings. Tokens created there last until you revoke them.

My agent says it is being slowed down.

Each token can make up to 60 calls a minute. Wait a minute and try again.

Where can I get help?

Official documentation

Need help? Contact support.