# Connect MCP-compatible clients to your MCP server

**Before you start**

- [Build an MCP server](https://clerk.com/docs/guides/ai/mcp/build-mcp-server.md?sdk=expressjs)

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](https://clerk.com/docs/expressjs/guides/ai/mcp/build-mcp-server.md).

This guide connects clients to your own endpoint. To let a coding agent manage your Clerk account instead, use [Clerk's MCP server](https://clerk.com/docs/guides/ai/mcp/clerk-mcp-server.md?sdk=expressjs).

## Connect an MCP client to your server

Use the server URL you configured in the [build and authenticate guide](https://clerk.com/docs/expressjs/guides/ai/mcp/build-mcp-server.md). Use `http://localhost:3000/mcp` for a local server on the same machine, or replace it with your deployed HTTPS endpoint. Select your client, then complete sign-in and consent.

### Development vs. Production Setup

- **Development**: In the Clerk Dashboard, add `http://localhost:3000/mcp` to a development instance on the [**MCP servers**](https://dashboard.clerk.com/~/agents/mcp-servers) page. Then start your server with the command in the build guide, and connect a client on the same machine.
- **Production**: Use your deployed URL (e.g., `https://your-domain.com/mcp`) for security and proper functionality.
  > Always use HTTPS URLs in production environments. HTTP connections are not secure and may not work with all MCP clients.

**Cursor**

### Connecting Cursor to your MCP server

1. Open **Customize** → **MCPs**, then select **New MCP Server**. You can also edit your project's `.cursor/mcp.json`.

2. Add the following configuration to the JSON file:

   ```json
   { "mcpServers": { "my-mcp-server": { "url": "http://localhost:3000/mcp" } } }
   ```

3. When Cursor prompts you, select **Authenticate** for the server. Cursor opens a Clerk OAuth consent screen where you authorize it to access your user data.

4. Select **Allow**. Cursor lists your tools as connected.

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?").

6. Select the **Run tool** option once it becomes available.

You've now successfully connected **Cursor** to your MCP server and authenticated it using Clerk.

**VSCode**

### Connecting VSCode to your MCP server

1. Open the Command Palette (`Cmd/Ctrl + Shift + P`) and run **MCP: Add Server**.

2. Select **HTTP**, enter your configured MCP endpoint, give the server a name, and choose a configuration destination.

3. Complete the trust and OAuth sign-in prompts. Alternatively, create `.vscode/mcp.json` in your project with this configuration:

   ```json
   {
     "servers": {
       "my-mcp-server": { "type": "http", "url": "http://localhost:3000/mcp" }
     }
   }
   ```

4. Use **MCP: List Servers** to start the server and complete sign-in if it hasn't started yet.

5. 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?").

6. Select the **Run tool** option once it becomes available.

You've now successfully connected **VSCode** to your MCP server and authenticated it using Clerk.

**Claude Code**

### Connecting Claude Code to your MCP server

1. Run the following command from your command line:
   ```bash
   claude mcp add --transport http my-mcp-server http://localhost:3000/mcp
   ```
2. Run `claude` to enter the Claude Code interface.
3. Execute the `/mcp` command to see available tools. From there, you can go through the authentication process to connect your MCP server.
4. 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**

### Connecting Claude Desktop to your MCP server

Use a remote connector with Claude's published Client ID Metadata Documents (CIMD) identity:

1. Open **Customize** → **Connectors**, select **+ Add**, then **Add custom connector**.
2. Enter a name and your public HTTPS MCP URL, then select **Continue**.
3. Select **Sign in now** and **Use Claude's published identity** for a CIMD-enabled Clerk instance, then finish adding the connector and sign in.
4. Enable the connector from **+** → **Connectors** in your chat, then ask for your Clerk user profile.

On Team and Enterprise plans, an authorized owner adds the connector from **Organization settings** → **Connectors** instead of steps 1–3. Each member then opens **Customize** → **Connectors**, selects **Connect** on the connector to sign in, and enables it as in step 4. See [Claude's current connector instructions](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for plan-specific permissions. Remote connectors connect from Claude's servers and can't reach localhost. Use your deployed HTTPS endpoint for this connection.

You've now successfully connected **Claude Desktop** to your MCP server and authenticated it using Clerk.

**Windsurf**

### Connecting Windsurf to your MCP server

These steps configure the legacy Cascade agent. The Devin Local agent, the default for new tabs, reads MCP servers from the [Devin CLI configuration](https://docs.devin.ai/cli/extensibility/mcp/configuration) instead.

1. In the Cascade panel, open the **...** (Actions) menu and select **Open MCP config file** in the MCPs section. On current releases, the file is `~/.config/devin/mcp_config.json` (or `$XDG_CONFIG_HOME/devin/mcp_config.json`) on macOS and Linux, and `%APPDATA%\devin\mcp_config.json` on Windows. Add your MCP server:

   ```json
   {
     "mcpServers": {
       "my-mcp-server": { "serverUrl": "http://localhost:3000/mcp" }
     }
   }
   ```

2. Save the file, turn on the server's toggle in the MCPs section, and follow the OAuth sign-in prompt.

3. Ask the client to call `get_clerk_user_data` and inspect the result. See the [current client documentation](https://docs.devin.ai/desktop/cascade/mcp) for configuration controls.

You've now successfully connected **Windsurf** to your MCP server and authenticated it using Clerk.

## Expected Response Format

When you successfully connect and authenticate your MCP client, prompting for your Clerk user data should return information similar to:

```json
{
  "id": "user_example",
  "firstName": "Alex",
  "lastName": "Example",
  "imageUrl": "https://example.com/avatar.png",
  "email": "alex@example.com"
}
```

The example server from the build guide requires `profile` and `email` and returns only profile fields and the primary email address. It excludes private metadata and other Backend API user fields. Your client may format the response differently.

## Not Currently Supported

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:

- **Cline**: While it does have MCP support, their implementation is not compatible with the latest MCP spec.

## Troubleshooting

If you encounter issues connecting your MCP client:

1. **Authentication fails**: On the [**OAuth applications**](https://dashboard.clerk.com/~/oauth-applications) page in the Clerk Dashboard, check the client's status and metadata on the **Applications** tab. Refresh metadata if the fetch failed. Use a CIMD-compatible client and review [client admission](https://clerk.com/docs/guides/configure/auth-strategies/oauth/client-id-metadata-documents.md?sdk=expressjs) if Clerk blocks the connection. If the client only supports Dynamic Client Registration, enable **Publish DCR support** under **Client onboarding** on the **Settings** tab.
2. **Public discovery fails or is stale**: For a hosted URL, review the saved findings in the [setup verification steps](https://clerk.com/docs/expressjs/guides/ai/mcp/build-mcp-server.md#verify-authentication-and-authorization). Correct the metadata, endpoint reachability, or issuer configuration, and deploy the fix. Then select **Re-test connection** on the server's page in the Clerk Dashboard, or call `check_mcp_server` with `force_recheck: true`. A check failure doesn't undo the saved URL.
3. **Connection refused**: Verify your MCP server is running and accessible at the specified URL.
4. **HTTPS errors**: Make sure you're using HTTPS URLs in production environments.
5. **Tool not available**: Confirm your client displays the tool in the list of available tools, and that the tool has been properly implemented.

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)