Authentication
The MCP server uses OAuth, not the REST API's x-api-key header. There is no key to copy: your client redirects you to log in to your Abyssale account and approve the specific permissions it's asking for, then connects with a token that carries only those permissions.
Not every role can use the MCP server
Connecting requires an Abyssale account with the Owner, Admin, Manager, Designer, or Operator role on the workspace. Viewer and Light Operator accounts can't use any tool that touches workspace data, not even to read. The one exception is get_design_import_example, which returns built-in examples and works for every role. Some tools narrow this further; see Permissions for the exact role each one needs.
This is a different credential from the REST API key
Your REST API x-api-key (see Authentication) and an MCP client's OAuth token are unrelated. One does not substitute for the other, and revoking one has no effect on the other.
Permissions are per client, per connection
Approval is scoped to the client you're connecting (a specific client connection), not blanket access to your account. You can, for example, allow one client to read your designs without allowing it to spend generation credits — see the scopes below.
Scopes
Every scope below except the first three gates a specific set of tools — see Tools reference for what each tool does.
| Scope | Grants | Tools |
|---|---|---|
openid, profile, email | Baseline identity — who you are. Requested on every connection. | — |
read:design | Read designs and their layers. | list_designs, search_designs, get_design, get_design_as_import, get_design_format, get_design_import_example |
read:project | Read projects (campaigns/folders). | list_projects |
write:project | Create projects. | create_project |
read:font | Read the font catalog. | list_fonts |
read:credits | Read the workspace's remaining credit balance. | get_remaining_credits |
write:design | Rename designs and move them between projects. | rename_design, move_design |
delete:design | Delete designs, with no undo. | delete_design |
import:design | Create designs from a JSON structure. | import_design_from_json, check_design_import_status |
generate:banner | Generate images, video, HTML5 and PDFs — spends credits. | generate_static_banner, generate_banners_async, generate_multipage_pdf, check_generation_status |
get_me (identity lookup only) requires no scope beyond being signed in — it's the one tool every connected client can always call.
What happens without valid credentials
| Situation | Response |
|---|---|
No Authorization header on the request | 401 authentication_required |
Header present but not Bearer <token> | 400 invalid_request |
| Token invalid, expired, or fails signature verification | 401 authentication_required |
| Token valid but missing an identity claim | 401 authentication_required |
| Token valid, but no Abyssale account is linked to it | Tool call fails: "No Abyssale account is linked to this identity." |
| Token valid, but missing a scope the requested tool needs | 403 insufficient_scope |
| Token valid, but your Abyssale role doesn't allow the tool | Tool call fails: role_access_denied |
| Request body larger than 10 MB | 413 payload_too_large |
| Several JSON-RPC requests sent as one batch (an array) | 400 — batch requests are not supported |
Most of these are HTTP errors your MCP client handles before you ever see a tool run. insufficient_scope is one of them: the 403 names the missing permission so your client can ask you to approve it — or reconnect and grant it yourself. Only two come back as a normal tool result: "no linked account", if you approved the connection with an identity that has no matching Abyssale user, and role_access_denied, if your role on the workspace doesn't allow that tool (see Permissions).