---
title: Use Clerk's MCP server
description: Connect AI agents to Clerk's MCP server to manage your Clerk applications, users, and production setup, and to get Clerk SDK snippets.
---

Clerk provides a remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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, 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](#sign-in-with-your-clerk-account) 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](#set-up-your-ai-client) for each client. Sign-in opens your browser so you can:

1. Sign in to Clerk.
1. Select the workspace your agent can access.
1. 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](/docs/guides/dashboard/manage-team-access) allows. It requests the following permissions:

| Scope | Allows the server to |
| - | - |
| `user:org:read` | Identify the workspace you selected |
| `applications:read` | Read the applications in that workspace |
| `applications:manage` | Create applications and production instances, and read and change instance configuration, such as OAuth credentials |
| `users:read` | List the users of an instance |
| `users:manage` | Create users |
| `application_domains:read` | Read domains, the DNS records they need, and their verification status |
| `application_domains:manage` | Start a DNS check for a domain |

## Set up your AI client

Select your AI client below to see its setup instructions.

<Tabs items={["Claude", "Codex", "Cursor", "fx", "VSCode", "Windsurf", "Zed", "Other clients"]}>
  <Tab>
    ### Connecting Claude to Clerk's MCP server

    <Tabs items={["Claude Code", "Claude.ai", "Claude Desktop"]}>
      <Tab>
        1. Run the following command to add Clerk's MCP server:
           ```sh {{ filename: 'terminal' }}
           claude mcp add clerk --transport http https://mcp.clerk.com/mcp
           ```
        1. In a Claude Code session, run `/mcp`, select **clerk**, and choose **Authenticate**. Your browser opens so you can sign in.
      </Tab>

      <Tab>
        1. Navigate to **Customize** → **Connectors**.
        1. Select **+ Add**, then **Add custom connector**.
        1. Enter **Clerk** as the name and `https://mcp.clerk.com/mcp` as the URL, then select **Continue**.
        1. Under **Authentication**, make sure **Sign in now** is selected. Under **OAuth client**, make sure **Use Claude's published identity** is selected.
        1. Select **Add**, then sign in.
        1. 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**.
      </Tab>

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

  <Tab>
    ### Connecting Codex to Clerk's MCP server

    <Tabs items={["Configuration via CLI", "Configuration through the config file"]}>
      <Tab>
        Run the following command in the terminal:

        ```sh {{ filename: '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`.
      </Tab>

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

  <Tab>
    ### Connecting Cursor to Clerk's MCP server

    <AddToCursorButton
      href="https://cursor.com/en-US/install-mcp?name=clerk&config=eyJ1cmwiOiJodHRwczovL21jcC5jbGVyay5jb20vbWNwIn0%3D"
    />

    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**.
    1. Select **New MCP Server**, which opens the MCP configuration JSON file.
    1. Add the following configuration to the JSON file:

    ```json
    {
      "mcpServers": {
        "clerk": {
          "url": "https://mcp.clerk.com/mcp"
        }
      }
    }
    ```

    4. Under **Needs attention**, select **Authenticate** next to **clerk** and sign in through your browser. Once connected, the server moves to **Connected**.
  </Tab>

  <Tab>
    ### Connecting fx to Clerk's MCP server

    [fx](https://fx.sh) is Vercel's open-source coding agent for the terminal.

    <Tabs items={["Configuration via CLI", "Configuration through the config file"]}>
      <Tab>
        1. Run the following command in the terminal:
           ```sh {{ filename: '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`.
        1. Run `fx mcp auth clerk` to sign in through your browser.
        1. Run `fx mcp list --connect` to verify the connection.
      </Tab>

      <Tab>
        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.
        1. Add the following configuration:
           ```json
           {
             "mcp": {
               "clerk": {
                 "type": "http",
                 "url": "https://mcp.clerk.com/mcp"
               }
             }
           }
           ```
        1. Run `/mcp reload` in an fx session to apply the change without restarting fx.
        1. Run `fx mcp auth clerk` to sign in through your browser.
      </Tab>
    </Tabs>
  </Tab>

  <Tab>
    ### Connecting VSCode to Clerk's MCP server

    1. Press `Cmd/Ctrl + Shift + P` and search for **MCP: Add Server**.
    1. Depending on your preferred transport method, follow the instructions below:

       <Tabs items={["HTTP", "Stdio"]}>
         <Tab>
           Enter the following URL and hit enter: `https://mcp.clerk.com/mcp`
         </Tab>

         <Tab>
           Enter the following command and hit enter:

           ```bash
           npx mcp-remote https://mcp.clerk.com/mcp
           ```
         </Tab>
       </Tabs>
    1. Enter the name **Clerk** and hit enter.
    1. When VS Code asks you to authenticate the server, allow it and sign in through your browser.
  </Tab>

  <Tab>
    ### Connecting Windsurf to Clerk's MCP server

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

  <Tab>
    ### Connecting Zed to Clerk's MCP server

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

  <Tab>
    ### 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`.
  </Tab>
</Tabs>

## Available tools

### Account tools

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

| Tools | Description |
| - | - |
| `whoami` | Show the connected user, workspace, and granted permissions. |
| `list_applications`, `get_application`, `create_application` | List, inspect, and create applications. Results include each instance's publishable key. |
| `get_instance_config`, `get_instance_config_schema`, `patch_instance_config`, `put_instance_config` | Read, update, or replace instance configuration, and read its schema. Preview changes with a dry run. |
| `list_users`, `create_user` | Find users with filters and create users in an instance. |
| `list_domains`, `get_domain_status`, `check_domain_dns` | Get the DNS records a domain needs, check its verification status, and request a new DNS check. |
| `get_deploy_oauth_providers`, `create_production_instance`, `set_oauth_provider_credentials` | Create a production instance from development and configure production OAuth credentials. Creating a production instance can't be undone, so the tool requires `confirm: true`. |
| `submit_feedback` | Report problems and missing documentation to the Clerk team. |
| `get_more_tools` | Tell the Clerk team about a task none of the other tools can do. |

### SDK snippet tools

| Tool | Description |
| - | - |
| `clerk_sdk_snippet` | Get 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_snippets` | List 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"
- "Check which DNS records are required for production"
- "How do I use the useUser hook in Clerk?"
- "Show me how to set up B2B SaaS with Clerk Organizations"

## 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?

No. The MCP server never returns your instances' secret keys, including when it creates an application or a production instance. It also redacts sensitive values when it reads instance configuration. To add your keys to a project, copy them from the [**API keys**](https://dashboard.clerk.com/~/api-keys) page in the Clerk Dashboard or run [`clerk env pull`](/docs/cli).

### Why does a tool return a permission error?

Your [workspace Role](/docs/guides/dashboard/manage-team-access) 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?

Every tool asks your agent for a one-sentence `context` that describes what you're trying to do. Your agent writes this summary and is told to leave out names, email addresses, IDs, and secrets. When your agent calls a tool, the server sends the summary to Clerk for product analytics. The server also adds which tool your agent called, whether the call succeeded, your Clerk user ID, and your AI client's name, version, and OAuth client ID. It doesn't send the tool's inputs or results. When your agent calls `get_more_tools`, the server records the task it couldn't complete, so the Clerk team can see which tools to add next.

### 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`.