āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā ā š shadcn/directory/clerk/clerk-docs/guides/development/mcp/connect-mcp-client ā āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
<TutorialHero beforeYouStart={[ { title: "Build an MCP server", link: "/docs/guides/development/mcp/build-mcp-server", icon: "clerk", } ]} />
This guide demonstrates how to connect an MCP-compatible client (LLM app), like Cursor, to an MCP server. It assumes that you have already built an MCP server in your application with Clerk by following the guide on building an MCP server.
To complete the integration, you'll need to connect an MCP-compatible client to your MCP server. Each client has a different way of connecting to MCP servers, and given that the MCP spec is still in development, you may need to refer to the client's documentation for the most up-to-date instructions.
[!IMPORTANT] For most client implementations of MCP, dynamic client registration is required. This allows MCP-compatible clients to automatically register themselves with your server during the OAuth flow. Before proceeding, ensure you have toggled on the Dynamic client registration option in the OAuth Applications page in the Clerk Dashboard.
npm run dev and use http://localhost:3000/mcp as your server URL.https://your-domain.com/mcp) for security and proper functionality.
[!WARNING] Always use HTTPS URLs in production environments. HTTP connections are not secure and may not work with all MCP clients.
<Tabs items={["Cursor", "VSCode", "Claude Code", "Claude Desktop", "Windsurf"]}> <Tab> ### Connecting Cursor to your MCP server
1. Navigate to **Cursor Settings**. To find this, open the **Command Palette** (`Cmd/Ctrl + Shift + P`) and search for **Cursor Settings**, or select the gear icon in the top right corner of the app.
1. In the sidenav, select **Tools & Integrations**. If you don't see this, you may need to update Cursor to the latest version.
1. Click the **New MCP Server** button, which will open up a new tab with the MCP configuration JSON file.
1. Add the following configuration to the JSON file:
```json
{ "mcpServers": { "clerk-mcp-server": { "url": "http://localhost:3000/mcp" } } }
```
> [!IMPORTANT]
> Replace `http://localhost:3000/mcp` with your production URL if you've deployed your MCP server.
5. Select the **Needs login** option when it loads. You'll be redirected to a Clerk OAuth consent screen to authorize Cursor to access your user data.
5. Select **Allow**. Once authorized, your tool(s) should be listed as enabled and you should see a green active status.
5. Start a new chat in [**Agent Mode**](https://docs.cursor.com/chat/agent) and prompt it to fetch your Clerk user data (e.g., "What is my Clerk user data?").
5. Select the **Run tool** option once it becomes available.
You've now successfully connected **Cursor** to your MCP server and authenticated it using Clerk.
1. Navigate to **Settings**. To find this, use the app menu to select **Settings** or press `Cmd/Ctrl + ,`.
1. In the settings searchbar, search for "MCP" and select the **Edit in settings.json** option.
1. Add the following configuration to the JSON file:
```json
{
"mcp": { "inputs": [], "servers": { "clerk-mcp-server": { "url": "http://localhost:3000/mcp" } } }
}
```
> [!IMPORTANT]
> Replace `http://localhost:3000/mcp` with your production URL if you've deployed your MCP server.
1. Select **Start** above the server URL to start the MCP server. This will open up a modal asking you to open a browser to authenticate.
1. Select **Allow**. Once authorized, your tool(s) should be listed as enabled and you should see **āļø Running** above the server URL.
1. Start a new Copilot chat (`Cmd/Ctrl + Shift + I`) and prompt it to fetch your Clerk user data (e.g. "What is my Clerk user data?").
1. Select the **Run tool** option once it becomes available.
You've now successfully connected **VSCode** to your MCP server and authenticated it using Clerk.
1. Run the following command from your command line:
```bash
claude mcp add --transport http clerk-mcp-server http://localhost:3000/mcp
```
> [!IMPORTANT]
> Replace `http://localhost:3000/mcp` with your production URL if you've deployed your MCP server.
1. Run `claude` to enter the Claude Code interface.
1. Execute the `/mcp` command to see available tools. From there, you can go through the authentication process to connect your MCP server.
1. Once connected, you can prompt Claude Code to execute the tool with something like "What is my Clerk user data?".
You've now successfully connected **Claude Code** to your MCP server and authenticated it using Clerk.
Claude Desktop offers two ways to connect to MCP servers:
- Using the **Search and Tools** menu in the main UI.
- Using the **Developer Settings**.
<Tabs items={["Using the Search and Tools menu", "Using the Developer Settings"]}>
<Tab>
1. In the main chat UI, navigate to the **Search and Tools** menu (icon with two horizontal lines and dots), then select **Manage Connectors**.
1. Scroll to the bottom and select **Add Custom Connector**.
1. Add your MCP server name and URL, then select **Add**.
1. Once added, your server will appear in the connectors list. Select the **Connect** option to establish the connection.
1. Once connected, you can open a new chat and prompt it to fetch your Clerk user data (e.g., "What is my Clerk user data?").
</Tab>
<Tab>
1. Navigate to **Settings**. To find this, use the app menu to select **Settings** or press `Cmd/Ctrl + ,`.
1. In the settings sidebar, select **Developer**, then **Edit config**. Open the revealed file in your editor of choice.
1. Add the following configuration to the JSON file:
```json
{
"mcpServers": {
"clerk-mcp-server": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:3000/mcp", "--allow-http"]
}
}
}
```
> [!IMPORTANT]
>
> - Replace `http://localhost:3000/mcp` with your production URL and remove `--allow-http` if you've deployed your MCP server.
> - [mcp-remote](https://github.com/geelen/mcp-remote) is required since this connection mode does not support remote MCP servers with authentication natively.
1. Restart Claude Desktop. It should now prompt you to authenticate with your Clerk account.
1. Once authenticated, you can open a new chat and prompt it to fetch your Clerk user data (e.g., "What is my Clerk user data?").
</Tab>
</Tabs>
You've now successfully connected **Claude Desktop** to your MCP server and authenticated it using Clerk.
1. Navigate to **Settings**. To find this, use the app menu to select **Settings** or press `Cmd/Ctrl + ,`.
1. In the settings searchbar, search for "MCP" and select the **Manage plugins** button under the **Plugins (MCP Servers)** section. Click the **View raw config** button to open the config file.
1. Add the following configuration to the JSON file:
```json
{
"mcpServers": {
"clerk-mcp-server": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:3000/mcp", "--allow-http"]
}
}
}
```
> [!IMPORTANT]
>
> - Replace `http://localhost:3000/mcp` with your production URL and remove `--allow-http` if you've deployed your MCP server.
> - [mcp-remote](https://github.com/geelen/mcp-remote) is required since Windsurf does not support remote MCP servers with authentication natively.
1. Save the file. It should now prompt you to authenticate with your Clerk account.
1. Once authenticated, you can open a new chat and prompt it to fetch your Clerk user data (e.g., "What is my Clerk user data?").
You've now successfully connected **Windsurf** to your MCP server and authenticated it using Clerk.
When you successfully connect and authenticate your MCP client, prompting for your Clerk user data should return information similar to:
User ID: <user-id>
Username: <username>
First Name: <first-name>
Last Name: <last-name>
Primary Email: <primary-email>
Secondary Email: <secondary-email>
2FA Enabled: No
Account Banned: No
Account Locked: No
Profile Image: <profile-image>
External Accounts: <external-account>
Organization Creation Enabled: Yes
Delete Self Enabled: Yes
The exact response will vary based on your specific Clerk user profile and the prompt you use with your LLM client.
The MCP protocol and spec are still in development, and as a result, implementation across clients can vary. While we are working to support all clients, there are some clients that are not currently supported:
If you encounter issues connecting your MCP client:
ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā