Skip to main content

Connect MCP-compatible clients to your MCP server

Before you start

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.

This guide connects clients to your own endpoint. To let a coding agent manage your Clerk account instead, use Clerk's MCP server.

Connect an MCP client to your server

Use the server URL you configured in the build and authenticate guide. 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 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.

    Warning

    Always use HTTPS URLs in production environments. HTTP connections are not secure and may not work with all MCP clients.

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:

    { "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 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.

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:

    {
  "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.

Connecting Claude Code to your MCP server

  1. Run the following command from your command line: 
    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.

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

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 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:

    {
  "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 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:

{
  "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 page in the Clerk Dashboard, check the client's status and metadata on the Applications tab. Refresh metadata if the fetch failed. Use a -compatible client and review client admission 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. 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.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub