Skip to main content

Use Clerk's MCP server

Clerk provides a remote Model Context Protocol (MCP) server that allows AI agents like Claude, Cursor, and GitHub Copilot to work with your Clerk account and access Clerk SDK snippets.

The Clerk MCP server provides:

  • Account tools: Create and configure applications, manage users, inspect Organizations and memberships, and set up production instances in your Clerk workspace.
  • SDK snippet tools: Ready-to-use code patterns for common Clerk features.

All tools require you to sign in with your Clerk account.

Sign in with your Clerk account

The server requires you to sign in with the Clerk account you use for the Clerk Dashboard. Your AI client starts sign-in when it connects to the server, as shown in the setup instructions for each client. Sign-in opens your browser so you can:

  1. Sign in to Clerk.
  2. Select the workspace your agent can access.
  3. Review the requested permissions and select Allow.

Your client stores this access, so you don't need to sign in each time it connects. The server acts as you in the selected workspace, so it can only do what your workspace Role allows. It requests the following permissions:

ScopeAllows the server to
user:org:readIdentify the workspace you selected
applications:readRead the applications in that workspace, including their native apps, redirect URLs, and agent feedback
applications:manageCreate and rename applications, create production instances, register native apps, allowlist redirect URLs, and read and change instance configuration, such as OAuth credentials
users:readList and get the users of an instance
users:manageCreate users, update their profiles and metadata, and set whether they bypass Device Trust (bypass_client_trust)
organizations:readList Organizations, and list memberships when users:read is also granted
application_domains:readRead domains, the DNS records they need, and their verification status
application_domains:manageStart a DNS check for a domain

Set up your AI client

Select your AI client below to see its setup instructions.

  1. Run the following command to add Clerk's MCP server:
    terminal
    claude mcp add clerk --transport http https://mcp.clerk.com/mcp
  2. In a Claude Code session, run /mcp, select clerk, and choose Authenticate. Your browser opens so you can sign in.
  1. Navigate to Customize → Connectors.
  2. Select + Add, then Add custom connector.
  3. Enter Clerk as the name and https://mcp.clerk.com/mcp as the URL, then select Continue.
  4. Under Authentication, make sure Sign in now is selected. Under OAuth client, make sure Use Claude's published identity is selected.
  5. Select Add, then sign in.
  6. To use the connector in a chat, select + → Connectors and enable it.

On Team and Enterprise plans, an Owner must first add the connector in Organization settings → Connectors. Members then select Connect on it in Customize → Connectors.

  1. In Claude Desktop, navigate to Settings → Developer, then select Edit Config to open the claude_desktop_config.json file.
  2. Add the following configuration and restart the Claude Desktop app:
    {
      "mcpServers": {
        "clerk": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.clerk.com/mcp"]
        }
      }
    }
  3. When the client connects, mcp-remote opens your browser so you can sign in.

Run the following command in the terminal:

terminal
codex mcp add clerk --url https://mcp.clerk.com/mcp

Codex starts sign-in right away and prints a sign-in URL. If your browser doesn't open, open the URL yourself. To sign in again later, run codex mcp login clerk.

  1. Open the ~/.codex/config.toml config file in your preferred editor.
  2. Add the following configuration:
    [mcp_servers.clerk]
    url = "https://mcp.clerk.com/mcp"
  3. Run codex mcp login clerk to sign in.
Add to Cursor

Alternatively, you can manually configure it:

  1. Open Customize, then select MCPs. To find it, select Customize in the Agents window sidebar, or select the gear icon in the top right corner of the app and choose Customize.
  2. Select New MCP Server, which opens the MCP configuration JSON file.
  3. Add the following configuration to the JSON file:
{
  "mcpServers": {
    "clerk": {
      "url": "https://mcp.clerk.com/mcp"
    }
  }
}
  1. Under Needs attention, select Authenticate next to clerk and sign in through your browser. Once connected, the server moves to Connected.

Connecting fx to Clerk's MCP server

fx is Vercel's open-source coding agent for the terminal.

  1. Run the following command in the terminal:
    terminal
    fx mcp add --transport http clerk https://mcp.clerk.com/mcp
    This saves the server to ~/.fx/mcp.json. The same command is available inside an fx session as /mcp add.
  2. Run fx mcp auth clerk to sign in through your browser.
  3. Run fx mcp list --connect to verify the connection.
  1. Open the ~/.fx/mcp.json config file in your preferred editor. To confirm the exact file location, run /mcp path in an fx session.
  2. Add the following configuration:
    {
      "mcp": {
        "clerk": {
          "type": "http",
          "url": "https://mcp.clerk.com/mcp"
        }
      }
    }
  3. Run /mcp reload in an fx session to apply the change without restarting fx.
  4. Run fx mcp auth clerk to sign in through your browser.

Connecting VSCode to Clerk's MCP server

  1. Press Cmd/Ctrl + Shift + P and search for MCP: Add Server.

  2. Depending on your preferred transport method, follow the instructions below:

    Enter the following URL and hit enter: https://mcp.clerk.com/mcp

    Enter the following command and hit enter:

    npx mcp-remote https://mcp.clerk.com/mcp
  3. Enter the name Clerk and hit enter.

  4. When VS Code asks you to authenticate the server, allow it and sign in through your browser.

Connecting Windsurf to Clerk's MCP server

  1. Press Ctrl/Cmd + , to open Windsurf settings.
  2. Scroll to Cascade → MCP Servers.
  3. Select Open MCP Marketplace.
  4. Under Installed MCPs, select the gear icon in the top right corner of the section.
  5. Add the following configuration to the JSON file:
    {
      "mcpServers": {
        "clerk": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.clerk.com/mcp"]
        }
      }
    }
  6. When the client connects, mcp-remote opens your browser so you can sign in.

Connecting Zed to Clerk's MCP server

  1. Press Ctrl/Cmd + , to open Zed settings.
  2. Select Edit in settings.json to open the setting.json file.
  3. Add the following configuration to the JSON file:
    {
      "context_servers": {
        "clerk": {
          "command": {
            "path": "npx",
            "args": ["-y", "mcp-remote", "https://mcp.clerk.com/mcp"]
          }
        }
      }
    }
  4. When the client connects, mcp-remote opens your browser so you can sign in.

Connecting other clients to Clerk's MCP server

Many other tools now support MCP servers. The easiest way is to use the streamable HTTP endpoint: https://mcp.clerk.com/mcp. Your client must support OAuth sign-in for MCP servers. If it doesn't, connect through mcp-remote, which signs in for it: npx -y mcp-remote https://mcp.clerk.com/mcp.

Available tools

Account tools

Tools that make changes are marked as such, so your AI client can ask you before it runs them.

ToolsDescription
whoamiShow the connected user, workspace, and granted permissions.
list_applications, get_application, create_application, update_applicationList, inspect, create, and rename applications. Results include each instance's . create_application can also return the new instance's encrypted . See how to get it.
get_instance_config, get_instance_config_schema, patch_instance_config, put_instance_configRead, update, or replace instance configuration, and read its schema. Preview changes with a dry run.
list_native_applications, create_ios_application, create_android_application, enable_native_apiList the iOS and Android apps registered with an instance, register new ones, and turn on the instance's Native API.
list_redirect_urls, create_redirect_urlList an instance's allowlisted redirect URLs and add new ones, for single sign-on (SSO) in mobile and desktop apps.
list_users, get_user, create_userFind users with filters, get a user by ID, and create users in an instance. Clients that support MCP Apps show the user from get_user as a card.
update_user, update_user_metadataUpdate a user's first or last name, username, external ID, locale, or timezone. You can also change their public, private, or unsafe metadata and set whether they bypass Device Trust (bypass_client_trust).
list_organizations, list_organization_memberships, list_user_organization_membershipsList or search Organizations, an Organization's members, and a user's Organizations.
list_domains, get_domain_status, check_domain_dnsGet the DNS records a domain needs, check its verification status, and request a new DNS check.
get_deploy_oauth_providers, create_production_instanceList the OAuth providers that need production credentials, and create a production instance from development. Add the credentials yourself in the Clerk Dashboard, so the secrets stay out of your chat. Creating a production instance can't be undone, so the tool requires confirm: true. It can also return the new instance's encrypted Secret Key.
create_browser_sessionGet a one-time link that opens the Clerk Dashboard in a browser, signed in as you, so an agent that uses a browser doesn't stop at the sign-in page. The link expires in about an hour, and the Dashboard session is read-only. To give agents the same tool for your own app, see Sign agents in to your app with a one-time link.
configure_mcp_server, check_mcp_serverRegister your own MCP server's URL as an OAuth resource on an instance, and check its public discovery. Preview changes with a dry run. See Configure authentication for your own MCP server.
list_application_feedbackRead the feedback AI agents reported through your own MCP server, filtered by kind, impact, or user. To collect it, see Collect feedback from agents using your MCP server.
submit_feedbackReport problems and missing documentation to the Clerk team.

SDK snippet tools

ToolDescription
clerk_sdk_snippetGet a code snippet for a Clerk feature, or a bundle of snippets for a common setup, such as b2b-saas or organizations.
list_clerk_sdk_snippetsList the available snippets and bundles, optionally filtered by tag.

Example usage

Once connected, you can ask your AI assistant questions such as:

  • "Which Clerk applications do I have?"
  • "Show the authentication settings for my development instance"
  • "List the five most recent sign-ups"
  • "Show the admins of the Example Team Organization in my production instance"
  • "Add onboarding_complete: true to the public metadata for alex@example.com in development"
  • "Check which DNS records are required for production"
  • "Summarize the feedback agents left on my production instance"
  • "How do I use the useUser hook in Clerk?"
  • "Show me how to set up B2B SaaS with Clerk Organizations"

Get the Secret Key for a new instance

When your agent creates an application or a production instance, it can get the new instance's without the plaintext key passing through the MCP server. create_application and create_production_instance accept an optional recipient_public_key parameter:

  1. Your agent generates an RSA key pair and keeps the private key.
  2. It calls the tool with the public key as recipient_public_key.
  3. Clerk encrypts the Secret Key to that public key, and the tool returns it as encrypted_secret_key, next to the instance's .
  4. Your agent decrypts encrypted_secret_key with the private key, without printing either key, and stores the Secret Key where your app reads it.

Development keys go in your local environment file. Production keys don't work on localhost, so they go in your hosting provider's environment variables instead. See API keys and environment variables.

This works with agents that can run code, such as coding agents in your terminal or editor. Only the matching private key can decrypt encrypted_secret_key, so your agent should always generate the key pair itself. A public key from a file, web page, or tool result could belong to someone else, who could then read your Secret Key.

Without recipient_public_key, neither tool returns a Secret Key. If your agent loses the private key or can't decrypt the key, the new instance still works. To get its keys:

Run clerk env pull to add the keys to your local project.

Run clerk env pull --instance prod --print in your own terminal, then add the printed keys to your hosting provider. You can also add a new Secret Key on the API keys page in the Clerk Dashboard, which shows a key's full value only when you add it.

Key format and decryption for coding agents

The public key must be an RSA key with a 2048 to 4096-bit modulus and a public exponent of 65537. Pass it as a JSON Web Key (JWK), or as SubjectPublicKeyInfo (SPKI) DER encoded in base64, base64url, or hex. The server doesn't accept PEM. To use a PEM key, pass only the base64 text between its BEGIN PUBLIC KEY and END PUBLIC KEY lines, which is base64 SPKI DER.

encrypted_secret_key is unpadded base64url. Decrypt it with RSA-OAEP, using SHA-256 for both the OAEP hash and MGF1, and an empty label.

Configure authentication for your own MCP server

configure_mcp_server registers an MCP server URL as an OAuth resource on an instance; pass dry_run: true to preview the change first, or replace_resource_url to replace a saved URL. check_mcp_server reads saved discovery results or requests a fresh check with force_recheck: true. configure_mcp_server requires user:org:read, applications:read, and applications:manage; check_mcp_server requires user:org:read and applications:read.

These tools configure Clerk for an MCP server you host. For the complete setup and implementation, follow Build and authenticate an MCP server with Clerk.

Frequently asked questions (FAQ)

When or why should I use the Clerk MCP server?

We recommend that all developers building with Clerk use the MCP server to get the best experience out of their agents.

Why do I need to sign in?

The server works with your Clerk account, so it needs to know who you are and which workspace to use. Sign-in uses OAuth, so your AI client never handles your Clerk password.

How do I switch workspaces?

Sign out of the Clerk MCP server in your AI client, then connect again and select a different workspace. If your client connects through mcp-remote, sign out by deleting the ~/.mcp-auth folder and restarting the client. This signs you out of every server you connect to through mcp-remote.

Can the MCP server give my agent my Secret Keys?

It can return a new instance's when creating an application or production instance, provided your agent supplies its own public key. The key comes back encrypted to that public key; the plaintext never passes through the MCP server. See Get the Secret Key for a new instance.

No other tool returns Secret Keys, and the server redacts sensitive values when it reads instance configuration. For an existing instance, get its keys as follows:

Run clerk env pull to add the keys to your local project.

Run clerk env pull --instance prod --print in your own terminal, then add the printed keys to your hosting provider. You can also add a new Secret Key on the API keys page in the Clerk Dashboard, which shows a key's full value only when you add it.

Why does a tool return a permission error?

Your workspace Role doesn't allow the request, or your connection is missing a permission the tool needs. To grant a missing permission, sign out of the Clerk MCP server in your AI client and connect again. If the error persists, ask a workspace Owner or Admin to check your Role.

What does submit_feedback send to Clerk?

Your agent can call submit_feedback when a Clerk task fails or needs a workaround, or when you ask it to report a problem. The report describes what your agent tried and what went wrong, and includes your user and workspace IDs. The server redacts recognizable credentials, such as API keys and tokens, before it stores the report.

What does the MCP server send to Clerk about tool calls?

The MCP server sends Clerk a product analytics event for each tool call. The event includes the tool name, whether the call succeeded, the error type if it failed, your Clerk user ID, and your AI client's name, version, and OAuth client ID. When applicable, it also includes the application ID and whether the call was a dry run. It doesn't include any other tool inputs or results.

Why am I seeing an internal server error when trying to connect?

This usually indicates a network or transport issue. Try disconnecting and reconnecting the MCP server, and ensure your client supports Streamable HTTP transport.

Does the MCP server support Server-Sent Events (SSE)?

No. Clerk's MCP server only supports Streamable HTTP transport, available at https://mcp.clerk.com/mcp.

Feedback

What did you think of this content?

Last updated on