Skip to content
Back to Docs
MCP Reference

Scopes

Scopes are the permission vocabulary that gates the /api/v1/* endpoints. Each scope grants exactly the operations its name suggests — e.g. prompts:write lets you create and update prompts but not delete them. Delete is its own scope so the OAuth consent screen can grant fine-grained access.

Full scope vocabulary

Every scope PromptOT supports, grouped by category. AI scopes consume billing credits and are opt-in.

Read
8

prompts:readList and fetch prompts in the project.
blocks:readList blocks attached to a prompt.
variables:readList variables defined on a prompt.
versions:readList versions and run diffs.
test_cases:readList test cases attached to prompts.
evals:readList historical evaluation runs and results.
projects:readList projects accessible to the key holder.
gallery:readBrowse the public prompt gallery.

Write
7

prompts:writeCreate and update prompts (does NOT include delete).
prompts:deletePermanently delete prompts. Separate so consent screens can grant fine-grained access.
blocks:writeCreate, update, delete, and reorder blocks.
variables:writeCreate, update, and delete variables.
versions:writeSave drafts and roll back versions.
versions:publishPromote a draft to published — fires the prompt.published webhook.
test_cases:writeCreate, update, and delete test cases.

AI
5

These scopes consume billing credits. Each call deducts from your monthly AI credit pool — generate keys without these scopes if you want zero AI spend.

evals:runTrigger new evaluation runs (consumes AI credits).
playground:runExecute prompts against an LLM in the playground (consumes AI credits).
ai:importUse AI to section a raw prompt string into typed blocks (consumes AI credits).
ai:rewriteUse AI to improve, expand, or simplify block content (consumes AI credits).
ai:copilotUse the prompt co-pilot to propose multi-block changes (consumes AI credits).

MCP key presets

The dashboard's Generate MCP Key button defaults to the MCP_DEFAULT_SCOPES set — all read/write/publish minus AI. Tick Allow AI features to additionally grant MCP_AI_SCOPES.

MCP_DEFAULT_SCOPES

Default scopes when AI features are off.

  • prompts:read
  • prompts:write
  • prompts:delete
  • blocks:read
  • blocks:write
  • variables:read
  • variables:write
  • versions:read
  • versions:write
  • versions:publish
  • test_cases:read
  • test_cases:write
  • evals:read
  • projects:read
  • gallery:read

MCP_AI_SCOPES

Added on top when "Allow AI features" is checked.

  • ai:import
  • ai:rewrite
  • ai:copilot
  • playground:run
  • evals:run

Backwards compatibility

API keys created before scopes existed default to ['prompts:read'] so the legacy GET /api/v1/prompts* delivery endpoints continue to work unchanged. No action is required from existing integrations — read-only delivery keeps working.

To use any of the new MCP tools or any mutating endpoint, generate a fresh key from the dashboard or upgrade an existing one with PATCH /api/api-keys/:id/scopes.

403 INSUFFICIENT_SCOPE

When a request reaches an endpoint whose required scope is not in the key's scope list, the API returns a 403 with the standard error envelope and a details object describing exactly what's missing.

json
{
"data": null,
"error": {
"code": "INSUFFICIENT_SCOPE",
"message": "Missing required scope: prompts:write",
"details": {
"required": ["prompts:write"],
"granted": ["prompts:read"],
"missing": ["prompts:write"]
}
}
}