{"openapi":"3.0.3","info":{"title":"PilotDeck MCP server and OAuth endpoints","version":"1.0.0","description":"The public surface for AI agents: the PilotDeck MCP server and the OAuth 2.1 endpoints clients sign in through. MCP clients do not need this file: they connect to the server URL and discover sign-in from the OAuth metadata. It is for tools that read OpenAPI. The available tools come from the MCP `tools/list` method and are listed in the MCP server reference.","contact":{"name":"PilotDeck support","email":"support@pilotdeck.co"}},"externalDocs":{"description":"PilotDeck MCP server reference","url":"https://docs.pilotdeck.co/ai-assistants/mcp-server"},"servers":[{"url":"https://api.pilotdeck.co","description":"Production"}],"tags":[{"name":"MCP","description":"The MCP server"},{"name":"OAuth","description":"Sign-in for MCP clients"}],"paths":{"/mcp":{"post":{"operationId":"mcpRequest","tags":["MCP"],"summary":"Send an MCP JSON-RPC 2.0 request","description":"Streamable HTTP, stateless, answered with JSON. Methods include `initialize`, `tools/list` and `tools/call`. A batch holds at most 20 calls and every call in it counts toward the limit of 60 tool calls a minute per token. A tool that cannot complete answers `200` with a JSON-RPC result that has `isError: true`.","security":[{"bearerToken":[]},{"oauth":["read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_site","arguments":{}}}}}},"responses":{"200":{"description":"JSON-RPC response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"More than 20 calls in one batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"BATCH_TOO_LARGE"}}}},"401":{"description":"No valid token. The `WWW-Authenticate` header points to the OAuth metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"TOKEN_INVALID"}}}},"402":{"description":"The account's plan does not include AI agent access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"PLAN_REQUIRED"}}}},"403":{"description":"The token's site is archived or inactive, or access was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"FORBIDDEN_SITE"}}}},"429":{"description":"More than 60 tool calls in the last minute for this token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMITED"}}}},"503":{"description":"Usage could not be checked, so the call was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"RATE_LIMIT_UNAVAILABLE"}}}}}},"get":{"operationId":"mcpGetNotAllowed","tags":["MCP"],"summary":"Not allowed: the server keeps no session","security":[],"responses":{"405":{"description":"Use POST.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"METHOD_NOT_ALLOWED"}}}}}},"delete":{"operationId":"mcpDeleteNotAllowed","tags":["MCP"],"summary":"Not allowed: the server keeps no session","security":[],"responses":{"405":{"description":"There is no session to end.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"METHOD_NOT_ALLOWED"}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getProtectedResourceMetadata","tags":["OAuth"],"summary":"Protected resource metadata (RFC 9728)","description":"Also served at `/.well-known/oauth-protected-resource/mcp`.","security":[],"responses":{"200":{"description":"Metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"operationId":"getAuthorizationServerMetadata","tags":["OAuth"],"summary":"Authorization server metadata (RFC 8414)","description":"Also served at `/.well-known/oauth-authorization-server/mcp`.","security":[],"responses":{"200":{"description":"Metadata.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/oauth/register":{"post":{"operationId":"registerClient","tags":["OAuth"],"summary":"Dynamic client registration (RFC 7591)","description":"Public clients only. At most 5 redirect URIs of up to 512 characters: https, or http on a loopback address. 10 registrations per 10 minutes per IP address.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["redirect_uris"],"properties":{"redirect_uris":{"type":"array","maxItems":5,"items":{"type":"string"}},"client_name":{"type":"string","maxLength":120},"client_uri":{"type":"string"},"logo_uri":{"type":"string"},"token_endpoint_auth_method":{"type":"string","enum":["none"]}}}}}},"responses":{"201":{"description":"Registered.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Redirect URIs are not valid, or a confidential client was requested.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"},"example":{"error":"invalid_redirect_uri"}}}},"429":{"description":"Too many registrations from this address. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"},"example":{"error":"temporarily_unavailable"}}}}}}},"/oauth/authorize":{"get":{"operationId":"authorize","tags":["OAuth"],"summary":"Start sign-in","description":"Sends the user to the PilotDeck consent page, where they pick a site and click Allow. Valid for 10 minutes. 30 sign-in starts per 10 minutes per IP address.","security":[],"parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string"}},{"name":"response_type","in":"query","required":true,"schema":{"type":"string","enum":["code"]}},{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string"}},{"name":"code_challenge_method","in":"query","required":false,"schema":{"type":"string","enum":["S256"]}},{"name":"scope","in":"query","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"}},{"name":"resource","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"302":{"description":"To the consent page, or back to `redirect_uri` with an OAuth error."},"400":{"description":"Unknown client, or the redirect URI is not registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"},"example":{"error":"invalid_client"}}}},"429":{"description":"Too many sign-in starts from this address. Carries `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"},"example":{"error":"temporarily_unavailable"}}}}}}},"/oauth/token":{"post":{"operationId":"exchangeToken","tags":["OAuth"],"summary":"Exchange a code or a refresh token","description":"Access tokens last 30 days and refresh tokens 90 days. Each refresh issues a new pair, revokes the old one and carries the scopes over.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"]},"client_id":{"type":"string"},"code":{"type":"string"},"code_verifier":{"type":"string"},"redirect_uri":{"type":"string"},"refresh_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Tokens.","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer","example":2592000},"refresh_token":{"type":"string"},"scope":{"type":"string"}}}}}},"400":{"description":"The code or refresh token is not valid, PKCE failed, or the grant type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"},"example":{"error":"invalid_grant"}}}},"401":{"description":"Unknown client.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"},"example":{"error":"invalid_client"}}}}}}},"/oauth/revoke":{"post":{"operationId":"revokeToken","tags":["OAuth"],"summary":"Revoke an access or refresh token (RFC 7009)","description":"Always answers `200`, whether or not the token existed.","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"Revoked, or the token never existed.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","description":"A token that starts with `pdk_`, created in PilotDeck under Settings > Integrations or issued through OAuth sign-in. One user, one site."},"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://api.pilotdeck.co/oauth/authorize","tokenUrl":"https://api.pilotdeck.co/oauth/token","refreshUrl":"https://api.pilotdeck.co/oauth/token","scopes":{"read":"Read the plan with its reasons, briefs, verified facts, drafts, AI visibility, competitors and usage","content:write":"Edit a draft's text and save it back","profile:write":"Edit the brand profile","visibility:write":"Add or change the tracked AI questions","competitors:write":"Add or change the competitors to research","social:write":"Give feedback on social posts"}}}}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"},"userMessage":{"type":"string"}}},"OAuthError":{"type":"object","properties":{"error":{"type":"string"},"error_description":{"type":"string"}}}}}}