# CreativeClaw MCP authentication

How an agent obtains credentials for the CreativeClaw remote MCP at https://app.creativeclaw.co/mcp.

This document describes the **live** OAuth 2.1 authorization-code flow. CreativeClaw does **not** implement WorkOS agent_auth identity_assertion, service_auth, or id-jag. Do not call invented identity_endpoint, claim_endpoint, or events_endpoint URLs — there are none.

## Discover

1. POST JSON-RPC to https://app.creativeclaw.co/mcp.
2. If the method requires a user (anything other than `initialize`, `notifications/initialized`, or `ping`) and no Bearer token is present, the server returns HTTP 401.
3. Read the `WWW-Authenticate` header. It is a Bearer challenge with `resource_metadata` pointing at RFC 9728 protected-resource metadata:
   - https://app.creativeclaw.co/.well-known/oauth-protected-resource/mcp
4. Fetch that document. `authorization_servers` lists Clerk. Fetch RFC 8414 metadata:
   - https://app.creativeclaw.co/.well-known/oauth-authorization-server
5. OpenID configuration (same issuer, same scopes): https://app.creativeclaw.co/.well-known/openid-configuration

agent_auth: not offered. identity_endpoint: not offered. identity_assertion: not offered. service_auth: not offered. id-jag: not offered. WWW-Authenticate is the discovery hint.

## Pick a method

Use OAuth 2.1 authorization code with PKCE S256. Dynamic client registration is available. Scopes are exactly `profile email`. Never request `openid` — Clerk rejects that scope for dynamically registered MCP clients.

## Register

POST to https://clerk.creativeclaw.co/oauth/register (RFC 7591 DCR). Use a public client with a PKCE code_challenge_method of S256.

## Claim

There is no identity claim or ID-JAG exchange. The user signs in at Clerk (typically Gmail) in the authorization step.

## Exchange

1. Send the user to https://clerk.creativeclaw.co/oauth/authorize with `response_type=code`, `code_challenge`, `code_challenge_method=S256`, `scope=profile email`, and your redirect URI.
2. POST the authorization code to https://clerk.creativeclaw.co/oauth/token with the PKCE `code_verifier`.
3. Store `access_token`. Refresh if a refresh_token is issued; do not request scopes the metadata does not list.

## Use the access_token

Send `Authorization: Bearer <access_token>` on every MCP POST that is not initialize/ping. JSON-RPC `tools/call` without a valid token stays 401.

Resource: https://app.creativeclaw.co/mcp
JWKS: https://clerk.creativeclaw.co/.well-known/jwks.json

## Errors

- HTTP 401 + WWW-Authenticate — missing, expired, or invalid token. Re-run authorization.
- `invalid_scope` from Clerk — you requested a scope other than profile/email (often `openid`). Drop it.
- Tool `isError: true` — authenticated, but the tool failed (credits, validation, provider). Not an auth error.

## Revocation

POST the token to https://clerk.creativeclaw.co/oauth/token/revoke. After revoke, the next `tools/call` is 401.

Human docs: https://creativeclaw.co/developers/
Markdown twin: https://creativeclaw.co/developers.md
OpenAPI: https://creativeclaw.co/openapi.json