Authentication

The hosted MCP server at mcp.moda.app/mcp supports two authentication methods. Pick whichever matches how you’ll be invoking it.

Which method should I use?

OAuth 2.1 — pick this when a human is driving

Use cases

Claude Desktop / claude.ai: everyday design work by you or your team.
Cursor / VS Code: a developer translating Moda designs to code, or generating UI.
Claude Code on your laptop: ad-hoc canvas queries from the terminal.
Claude mobile: carry-over of your desktop connector.

How it works. On first use, your client pops a browser, you sign in to Moda (via Clerk), and tokens get stored by the client. Every subsequent tool call is authenticated silently — you won’t see the sign-in again unless your session expires or you revoke access. Individual team members see their own canvases, orgs, and credits. What you get. Per-user identity. Every tool call runs as you; list_my_canvases returns the canvases you personally have access to, design tasks bill against your team’s credits, and audit logs attribute actions to your user.

API key — pick this when there’s no human in the loop

Use cases

Scheduled content generation. Daily social post at 9am? Weekly carousel? There’s no human to click a consent screen — the job needs a durable credential.
Claude Managed Agents. Anthropic’s platform-managed agents can run on a cron. They need a bearer token, not an OAuth flow.
CI/CD pipelines. Regenerating branded assets on merge to main, or running design smoke tests in GitHub Actions.
Server-side integrations. Your backend code calling the MCP directly (rather than wrapping the REST API) — a bot that drafts design tasks from a Slack command, or a webhook handler that kicks off tasks.
Internal tools your team uses across many sessions. Some teams prefer a stable, rotatable credential per integration instead of managing individual OAuth sessions per teammate.

How it works. Generate a key in Settings → Developer → REST API, then configure your MCP client to send Authorization: Bearer moda_live_.... The key ties every tool call to the team it was created under. What you get. Team-level identity. Every call runs as the key’s owner + team.

Rules of thumb

Situation	Use
”A person is clicking something and will see the result in chat”	OAuth
”A scheduled job runs at 3am”	API key
”Different teammates each connect their own editor”	OAuth (each person signs in as themselves)
“One service account drives a pipeline”	API key
”I need to rotate credentials regularly”	API key (revoke + regenerate in Settings; no end-user impact)
“I need the simplest possible setup”	OAuth (no key management)

Mixing both

The server accepts both methods simultaneously — you can have your own Cursor connected via OAuth, and a Claude Managed Agent connected with an API key, against the same Moda account. They don’t conflict; pick the right auth for each caller.

When is authentication required?

Action	Auth required
Fetch a public share link (`moda.app/s/...`)	No
Fetch a private canvas (`moda.app/canvas/...`)	Yes
List your canvases	Yes
Search your canvases	Yes

Public share links work without authentication in both local and remote server modes. Private canvases and canvas listing/searching require the remote server with either OAuth or an API key.

Setting up API-key auth

1. Generate a key

In your Moda account, go to Settings → Developer → REST API → Create API key. Copy the moda_live_... key — it’s shown once. Store it in a secret manager.

2. Configure your client

Claude Code
Cursor
VS Code
curl / scripts

claude mcp add moda https://mcp.moda.app/mcp \
  --transport http \
  --scope user \
  --header "Authorization: Bearer moda_live_..."

The URL must come immediately after the server name; --header uses an HTTP-style Name: value format with a colon, not =.--scope user keeps the key in your per-user Claude config rather than a repo-level file that could get committed.

Edit ~/.cursor/mcp.json (or project-level .cursor/mcp.json):

{
  "mcpServers": {
    "moda": {
      "type": "streamable-http",
      "url": "https://mcp.moda.app/mcp",
      "headers": {
        "Authorization": "Bearer moda_live_..."
      }
    }
  }
}

In user or workspace settings.json:

{
  "mcp": {
    "servers": {
      "moda": {
        "type": "streamable-http",
        "url": "https://mcp.moda.app/mcp",
        "headers": {
          "Authorization": "Bearer moda_live_..."
        }
      }
    }
  }
}

Any HTTP client can connect directly — useful for CI, smoke tests, or custom integrations:

curl -X POST https://mcp.moda.app/mcp \
  -H "Authorization: Bearer $MODA_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude Desktop and claude.ai don’t support custom headers in their connector UI today — they assume OAuth for remote MCPs. Use OAuth for Claude Desktop; reserve API keys for Cursor / VS Code / Claude Code / CLI / cron.

3. Identity

Every tool call authenticated with an API key runs as the key’s owner + team. list_my_canvases returns the key-owner’s canvases; start_design_task bills their team’s credits. Session context (set_context) persists per-user across calls, same as OAuth — different keys mean different owners, so multi-tenant reuse is safe.

4. Rotating or revoking a key

Go to Settings → Developer → REST API, revoke the key, and generate a new one. Update the bearer token in your MCP client config. No coordination with end-users needed — API keys are meant to rotate.

How the OAuth flow works

When you first use the MCP server, your editor initiates the OAuth flow:

Your editor sends a request to the MCP server
The server responds with 401 Unauthorized
Your editor discovers the OAuth endpoints automatically
A browser window opens for you to sign in via Moda (powered by Clerk)
After sign-in, tokens are exchanged and stored by your editor
All subsequent requests are authenticated automatically

If you’re already signed in to moda.app in your browser, the sign-in step is instant — your existing session is detected automatically.

Token lifecycle

Token	Lifetime	Notes
Access token	24 hours	Refreshed automatically by your editor
Refresh token	30 days	Rotated on each use for security

Your editor manages token refresh transparently. You should rarely need to re-authenticate unless you revoke access or your refresh token expires.

Local server authentication

The local stdio server does not use authentication. It can only access public share links. To access private canvases, use the remote server at mcp.moda.app.

Revoking access

OAuth sessions — remove the connector in the client:

Claude Desktop / claude.ai: Settings > Connectors → disconnect or remove the Moda connector.
Claude Mobile: Disconnect the Moda connector from claude.ai/settings, then restart the mobile app.
Claude Code: claude mcp remove moda.
Cursor: Remove the server from Cursor Settings > MCP.
VS Code: Remove the Moda entry from your MCP settings.json.

This removes the stored tokens locally. You’ll re-authenticate on next connect. API keys — revoke the key itself at Settings → Developer → REST API. Every client using that key loses access immediately across all sessions and devices. Generate a fresh key and update your client config to continue.

Security

OAuth 2.1 with PKCE (Proof Key for Code Exchange) prevents authorization code interception.
OAuth access tokens are short-lived JWTs (24 hours); refresh tokens are rotated on each use.
API keys are hashed at rest; only the moda_live_ prefix is logged for debugging. Lose a key? Revoke it in Settings → Developer.
A compromised or prompt-injected MCP call can’t use the key to rotate webhooks or read raw credit balances — MCP-originated requests are restricted to a safe subset of operations regardless of what the key itself allows at the REST layer.
All communication with mcp.moda.app uses TLS.
The MCP server never stores your Moda password — OAuth authentication is delegated to Clerk.

Documentation Index

​Which method should I use?

​OAuth 2.1 — pick this when a human is driving

​API key — pick this when there’s no human in the loop

​Rules of thumb

​Mixing both

​When is authentication required?

​Setting up API-key auth

​1. Generate a key

​2. Configure your client

​3. Identity

​4. Rotating or revoking a key

​How the OAuth flow works

​Token lifecycle

​Local server authentication

​Revoking access

​Security

Which method should I use?

OAuth 2.1 — pick this when a human is driving

API key — pick this when there’s no human in the loop

Rules of thumb

Mixing both

When is authentication required?

Setting up API-key auth

1. Generate a key

2. Configure your client

3. Identity

4. Rotating or revoking a key

How the OAuth flow works

Token lifecycle

Local server authentication

Revoking access

Security