​

MCP OAuth

​

Why OAuth?

• No token to copy into config files
• Scoped consent per application (read:tokens, write:tokens, export:tokens)
• Revocable from API Settings
• 30-day access tokens, automatically renewed on re-authorization

​

Discovery endpoints

{
  "issuer": "https://app.tokencraft.dev",
  "authorization_endpoint": "https://app.tokencraft.dev/mcp/authorize",
  "token_endpoint": "https://app.tokencraft.dev/api/oauth/mcp/token",
  "registration_endpoint": "https://app.tokencraft.dev/api/oauth/mcp/register",
  "revocation_endpoint": "https://app.tokencraft.dev/api/oauth/mcp/revoke",
  "scopes_supported": ["read:tokens", "write:tokens", "export:tokens"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_post", "none"]
}

​

Authorization flow

​

Steps

1. Authorize — Client redirects the user to /api/oauth/mcp/authorize with:
   • client_id, redirect_uri, response_type=code
   • scope (space-separated scopes)
   • state (CSRF protection)
   • code_challenge + code_challenge_method=S256 (PKCE, recommended)
2. Consent — User reviews the request on /mcp/authorize and approves or denies.
3. Code exchange — Client posts to /api/oauth/mcp/token:

curl -X POST https://app.tokencraft.dev/api/oauth/mcp/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://your-app/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=PKCE_VERIFIER"

4. Use token — Include the access token in MCP requests:

Authorization: Bearer <access_token>

​

Scopes

​

Dynamic client registration

curl -X POST https://app.tokencraft.dev/api/oauth/mcp/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": ["https://my-app.example/callback"]
  }'

​

Token lifecycle

• Authorization codes expire after 10 minutes and are single-use.
• Access tokens expire after 30 days.
• Tokens are stored in the api_tokens table and named MCP OAuth — {client name}.
• OAuth tokens are 64-character hex strings (no tkc_ prefix).
• They authenticate identically to manual API tokens via Authorization: Bearer.

​

Revocation

1. Dashboard — API Settings → delete the MCP OAuth — … token
2. API — POST /api/oauth/mcp/revoke with the token value

curl -X POST https://app.tokencraft.dev/api/oauth/mcp/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=ACCESS_TOKEN"

​

Connect a remote MCP client

​

Cursor

1. Open Cursor Settings → MCP
2. Add a remote server with URL: https://app.tokencraft.dev/api/mcp
3. On first use, Cursor opens the browser for OAuth consent
4. Approve the requested scopes — no manual token needed

​

Claude (remote MCP)

​

Figma plugin OAuth

1. Plugin opens /api/oauth/mcp/authorize in the system browser (client_id=figma-plugin-v1)
2. User logs in and consents
3. Browser redirects to /mcp/figma-callback?code=…&state=…
4. Plugin polls GET /api/oauth/figma-plugin/poll?state=… until the code is available
5. Plugin exchanges the code at /api/oauth/mcp/token with PKCE

​

Rate limits

​

Next steps