MCP authentication
Two ways to authenticate — Clerk OAuth or an API key.
The MCP server accepts two token types on the same Authorization: Bearer ... header. The server picks the right verifier from the token shape — you don’t.
Option 1: Clerk OAuth (recommended)
For interactive use. Most MCP clients trigger this flow automatically the first time they call the server: a browser tab opens, you sign into your DomainGenius account, pick the org, and approve the requested scopes. The client stores the resulting access token.
When the token expires, the client silently refreshes it. Revoke a session at /dashboard/sessions.
Option 2: API key
For headless use, CI, or when your client doesn’t support OAuth. Mint a key at /dashboard/api-keys, add it to the client config:
{
"headers": {
"Authorization": "Bearer dg_live_..."
}
}The exact JSON shape varies by client — see the install pages.
API keys carry per-key scopes. OAuth sessions get the default agent scope set:
| Scope | Granted to OAuth | Granted to keys |
|---|---|---|
availability:read | yes | only if minted with it |
orgs:read, orgs:write | yes | only if minted |
domains:read, domains:write | yes | only if minted |
dns:read, dns:write | yes | only if minted |
contacts:read, contacts:write | yes | only if minted |
billing:read, billing:write | no — must use a key | only if minted |
Billing actions are deliberately out-of-scope for OAuth — top-ups go through the dashboard or a key, not the assistant.
Failures
{ "error": { "code": -32001, "message": "Missing scope: dns:write" } }Code -32001 is auth-related (missing or revoked token, missing scope, missing org membership). Mint a wider key or sign in to a different org.