Skip to main content

​
MCP OAuth

Tokencraft hosts a remote MCP server at https://app.tokencraft.dev/api/mcp. MCP clients such as Cursor, Claude (remote MCP), and the Figma plugin authenticate via OAuth instead of pasting an API key.
For CI/CD and automation scripts, use manual API tokens instead of OAuth.

​
Why OAuth?

Use caseAuth
Cursor, Claude remote MCP, Figma pluginOAuth (this page)
CI/CD, GitHub Actions, scriptsAPI key (tkc_…) — Authentication
OAuth benefits:
  • 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

MCP clients discover OAuth metadata automatically:
EndpointPurpose
GET /.well-known/oauth-authorization-serverAuthorization server metadata (RFC 8414)
GET /.well-known/oauth-protected-resourceProtected resource metadata for /api/mcp
Example authorization server metadata: 
{
  "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"]
}
When a client calls /api/mcp without a token, the server responds with 401 and a WWW-Authenticate header pointing to the protected-resource metadata. The client then starts the OAuth flow.

​
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"
  1. Use token — Include the access token in MCP requests:
Authorization: Bearer <access_token>

​
Scopes

ScopeAccess
read:tokensList and read workspaces, tokensets, modes, tokens
write:tokensCreate, update, delete resources (subject to workspace permissions)
export:tokensExport tokensets and modes (JSON, CSS, iOS, Android)

​
Dynamic client registration

MCP clients can register automatically (RFC 7591): 
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"]
  }'
Response includes client_id and client_secret. Public clients using PKCE can authenticate with token_endpoint_auth_method: none.

​
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

Revoke a token in either way:
  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)

Add the hosted URL in your client’s remote MCP configuration. The client discovers OAuth via the well-known endpoints.

​
Figma plugin OAuth

The Figma plugin cannot receive browser redirects directly. It uses a polling bridge:
  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
See Figma Integration for the full plugin guide.

​
Rate limits

OAuth tokens share the same rate limits as manual API tokens: 100 requests per minute per token.

​
Next steps

Configuration

Hosted vs local MCP setup

Authentication

Manual API tokens for CI/CD

Tools

Available MCP tools

Figma

Figma plugin OAuth flow