# Sticklight auth.md

You are an agent. This document describes how to authenticate to **Sticklight MCP** on behalf of a signed-in user. Sticklight exposes a remote MCP server for building, editing, previewing, and publishing apps. Follow the steps in order.

Production hosts used below:

- **Site:** `https://sticklight.com`
- **MCP resource server:** `https://mcp.sticklight.com`
- **Authorization server:** `https://mcp.sticklight.com`
- **Identity provider (Descope):** `https://auth.sticklight.com`

Spec reference: RFC 9728 (Protected Resource Metadata) and RFC 8414 (Authorization Server Metadata).

## Step 1 — Discover

Discovery is two hops.

If you received a `401 Unauthorized` with a `WWW-Authenticate` header, fetch the Protected Resource Metadata (PRM) URL from `resource_metadata`. Otherwise, start at the PRM on the Sticklight site:

```http
GET https://sticklight.com/.well-known/oauth-protected-resource
```

PRM response shape:

```json
{
  "resource": "https://mcp.sticklight.com/mcp",
  "resource_name": "Sticklight MCP",
  "authorization_servers": ["https://mcp.sticklight.com"],
  "scopes_supported": ["openid"],
  "bearer_methods_supported": ["header"]
}
```

Then fetch Authorization Server metadata from the first `authorization_servers` entry:

```http
GET https://mcp.sticklight.com/.well-known/oauth-authorization-server
```

The sticklight.com mirror at `https://sticklight.com/.well-known/oauth-authorization-server` publishes the same issuer and endpoints. `openid-configuration` at `https://sticklight.com/.well-known/openid-configuration` adds `jwks_uri` for token verification.

Read these fields from the AS metadata:

- `registration_endpoint` — `https://mcp.sticklight.com/register`
- `authorization_endpoint` — `https://mcp.sticklight.com/authorize`
- `token_endpoint` — `https://mcp.sticklight.com/oauth/token`
- `revocation_endpoint` — `https://auth.sticklight.com/oauth2/v1/apps/revoke`
- `jwks_uri` — Descope JWKS (on the sticklight.com OIDC document)

## Step 2 — Register

Register your public OAuth client (PKCE, no client secret):

```http
POST https://mcp.sticklight.com/register
Content-Type: application/json

{
  "client_name": "My MCP Client",
  "redirect_uris": ["https://my-client.example/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

Response includes `client_id`. Keep it for the authorization step.

## Step 3 — Authorize

Send the user to `authorization_endpoint` with PKCE parameters (`code_challenge`, `code_challenge_method=S256`), `client_id`, `redirect_uri`, `response_type=code`, and `scope=openid`.

The user signs in with their Sticklight account. On success, your `redirect_uri` receives an authorization `code`. Exchange it at `token_endpoint`:

```http
POST https://mcp.sticklight.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&code_verifier=...
```

The response includes `access_token` (and optionally `refresh_token`).

## Step 4 — Use credentials

Call the MCP resource with the bearer token:

```http
POST https://mcp.sticklight.com/mcp
Authorization: Bearer <access_token>
Content-Type: application/json

{ "jsonrpc": "2.0", "method": "tools/list", "id": 1 }
```

Send `Authorization: Bearer` on every MCP request. Scopes are carried by the issued access token (`openid`).

## Step 5 — Errors

| Situation | What to do |
| --- | --- |
| `401 Unauthorized` on MCP | Re-run discovery; refresh or re-issue the access token. Check for `WWW-Authenticate: Bearer resource_metadata="https://mcp.sticklight.com/.well-known/oauth-protected-resource"`. |
| `invalid_grant` on token exchange | Authorization code expired or PKCE verifier mismatch — restart authorization at `authorization_endpoint`. |
| `invalid_client` on registration | Verify `redirect_uris`, `grant_types`, and that the client is registered as a public client (`token_endpoint_auth_method: none`). |
| User not signed in | Direct the user through `authorization_endpoint` before calling protected MCP tools. |

## Step 6 — Revocation

Revoke an access or refresh token at `revocation_endpoint`:

```http
POST https://auth.sticklight.com/oauth2/v1/apps/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_token_or_refresh_token>&token_type_hint=access_token
```

After revocation, discard local copies of the token and re-authenticate if the user needs MCP access again.