OAuth for MCP clients

This page is for people building an MCP client. If you use Claude Code, Codex or Cursor, the client does all of this for you — see the quickstarts. The theme MCP server follows the MCP authorization specification: OAuth 2.1 with PKCE, Protected Resource Metadata (RFC 9728), Authorization Server Metadata (RFC 8414), Dynamic Client Registration (RFC 7591) and Resource Indicators (RFC 8707).


Protected resource	`https://api.platformdtc.com/mcp/theme`
Resource metadata	`https://api.platformdtc.com/.well-known/oauth-protected-resource/mcp/theme`
Authorization server metadata	`https://api.platformdtc.com/.well-known/oauth-authorization-server`
Registration	`POST https://api.platformdtc.com/oauth/register`
Authorization	`GET https://api.platformdtc.com/oauth/authorize`
Token	`POST https://api.platformdtc.com/oauth/token`
Revocation	`POST https://api.platformdtc.com/oauth/revoke`
Scopes	`read_themes`, `write_themes`, `publish_themes`, `write_apps` (App Store partner apps)

1. Discover

Call the server without a token. It answers 401 and points at its metadata:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.platformdtc.com/.well-known/oauth-protected-resource/mcp/theme"

Fetch the protected resource metadata to find the authorization server, then fetch /.well-known/oauth-authorization-server for its endpoints. Read endpoints from the metadata rather than hard-coding them.

2. Register

Register once per installation. Clients are public clients — there is no client secret — so token_endpoint_auth_method is none.

curl -X POST https://api.platformdtc.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Theme Assistant",
    "redirect_uris": ["http://127.0.0.1:53682/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'
# -> { "client_id": "…", "client_name": "Acme Theme Assistant", "redirect_uris": [ … ], … }

client_name is what the merchant sees on the consent screen, and what the issued key is named after. Use your product’s real name. Because anyone can register a client, the consent screen labels a registered client Unverified app and shows the host the authorization goes to. Only PlatformDTC’s own clients, such as the dtc CLI (a pre-registered client that does not use this endpoint), are shown as verified.

3. Authorize

Create a PKCE verifier (43–128 characters) and its S256 challenge, then send the user’s browser to the authorization endpoint:

GET https://api.platformdtc.com/oauth/authorize
    ?response_type=code
    &client_id=<client_id>
    &redirect_uri=http://127.0.0.1:53682/callback
    &scope=read_themes%20write_themes%20publish_themes
    &state=<random>
    &code_challenge=<base64url(sha256(verifier))>
    &code_challenge_method=S256
    &resource=https://api.platformdtc.com/mcp/theme

The server validates the client, the exact redirect_uri, the PKCE challenge (S256 only) and the resource, then redirects the user to the PlatformDTC consent page. There the user signs in, sees your client_name, the host you will redirect to and the requested scopes, chooses a store, may remove scopes, and approves or denies. On approval the browser returns to your redirect_uri:

http://127.0.0.1:53682/callback?code=<code>&state=<random>

Check that state matches. The granted scopes may be fewer than you requested — read scope from the token response, and do not offer actions the grant does not cover.

4. Exchange the code

curl -X POST https://api.platformdtc.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=http://127.0.0.1:53682/callback \
  -d client_id=<client_id> \
  -d code_verifier=<verifier> \
  -d resource=https://api.platformdtc.com/mcp/theme

{
  "access_token": "sq_agt_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "scope": "read_themes write_themes"
}

The access token is an sq_agt_* Agent Gateway key: bound to the store the user chose, carrying only the granted scopes, expiring after 1 hour, and named OAuth: <client_name>. It works on the MCP server and directly on the Agent Gateway /themes endpoints.

5. Call the server

POST /mcp/theme HTTP/1.1
Host: api.platformdtc.com
Authorization: Bearer sq_agt_…
Content-Type: application/json
Accept: application/json, text/event-stream

6. Refresh

curl -X POST https://api.platformdtc.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token=<refresh_token> \
  -d client_id=<client_id>

Refresh tokens rotate: every refresh returns a new refresh token, and the old one stops working. A refresh token is valid for 60 days from its last use.

Reusing an old refresh token revokes the whole token family, and the user has to authorize again. Store the new refresh token before using the new access token, and never run two refreshes for the same credentials at the same time — serialize them in your client.

Refresh tokens are stored only as a hash on our side; if you lose one, authorize again.

7. Revoke

When the user disconnects your client, revoke its token:

curl -X POST https://api.platformdtc.com/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d token=<refresh_token_or_access_token> \
  -d client_id=<client_id>

Static keys for headless use

A CI job or a server with no browser can skip OAuth and send a static sq_agt_* key, created under Agents → Access → API keys with the theme scopes it needs:

Authorization: Bearer sq_agt_…

A static key does not expire on a timer. Give it the fewest scopes the job needs and revoke it when the job is retired.

Build with your agent

Theme reference

OAuth for MCP clients

1. Discover

2. Register

3. Authorize

4. Exchange the code

5. Call the server

6. Refresh

7. Revoke

Static keys for headless use

​1. Discover

​2. Register

​3. Authorize

​4. Exchange the code

​5. Call the server

​6. Refresh

​7. Revoke

​Static keys for headless use

1. Discover

2. Register

3. Authorize

4. Exchange the code

5. Call the server

6. Refresh

7. Revoke

Static keys for headless use