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 cannot use the MCP server at all — not even to read. 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 |
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 |
The first four are connection-level failures your MCP client should surface before you ever see a tool run. The last two surface as a normal tool result — "no linked account" if you approved the connection with an identity that has no matching Abyssale user, and "insufficient scope" if you try a tool your client wasn't approved for (re-connect and grant the scope it needs).