Skip to main content
Docs

Connect MCP-compatible clients to your MCP server built with Next.js

Before you start

If you're building an application and want to allow large language model (LLM) apps to securely access user data within your app, you'll need to set up a Model Context Protocol (MCP) server. MCP enables external tools like LLM-based apps to request user permission to access specific data from your service.

There are two parties involved in MCP - "client" and "server". In web development, the terms "client" and "server" often refer to the frontend (browser) and backend (web server). However, in this context, these terms have different meanings:

  • The "client" is the LLM application that wants to access another service on a user's behalf. For example, Claude would be the "client" if it wants to get access to Gmail.
  • The "server" is the system that hosts the protected resources the client wants to access. In this example, this would be Gmail. This is sometimes referred to as the "resource server" or "MCP server".

This guide demonstrates how to connect an MCP-compatible client (LLM app), like Cursor, to an MCP server built with Next.js. It assumes that you have already built an MCP server in your Next.js application with Clerk by following the guide on building an MCP server with Next.js.

Connect your client LLM to your 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

Before proceeding, ensure you have toggled on the Dynamic client registration option in the OAuth Applications page. This setting allows MCP-compatible clients to automatically register themselves with your server during the OAuth flow.

Development vs. Production Setup

  • Development: Start your MCP server by running npm run dev and use http://localhost:3000/mcp as your server URL.
  • Production: Use your deployed URL (e.g. https://yourdomain.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. 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.
  2. In the sidenav, select Tools & Integrations. If you don't see this, you may need to update Cursor to the latest version.
  3. Click the New MCP Server button, which will open up a new tab with the MCP configuration JSON file.
  4. Add the following configuration to the JSON file:
{ "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.

  1. 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.
  2. Select Allow. Once authorized, your tool(s) should be listed as enabled and you should see a green active status.
  3. Start a new chat in Agent Mode and prompt it to fetch your Clerk user data (e.g., "What is my Clerk user data?").
  4. 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. Navigate to Settings. To find this, use the app menu to select Settings or press Cmd/Ctrl + ,.
  2. In the settings searchbar, search for "MCP" and select the Edit in settings.json option.
  3. Add the following configuration to the JSON file: 
    {
  "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.

  4. 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.
  5. Select Allow. Once authorized, your tool(s) should be listed as enabled and you should see ✔️ Running above the server URL.
  6. 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?").
  7. 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 clerk-mcp-server http://localhost:3000/mcp

    [!IMPORTAIPRTANT] Replace http://localhost:3000/mcp with your production URL if you've deployed your MCP server.

  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

  1. Navigate to Settings. To find this, use the app menu to select Settings or press Cmd/Ctrl + ,.
  2. In the settings sidebar, select Developer, then Edit config. Open the revealed file in your editor of choice.
  3. Add the following configuration to the JSON file: 
    {
  "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 is required since Claude Desktop does not support remote MCP servers with authentication natively.
  4. Restart Claude Desktop. It should now prompt you to authenticate with your Clerk account.
  5. 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 Claude Desktop to your MCP server and authenticated it using Clerk.

Warning

Claude Desktop has a second way to connect to MCP servers under an "Integrations" menu, however, this is not currently supported due to an incompatible implementation of an older version of the MCP spec.

Connecting Windsurf to your MCP server

  1. Navigate to Settings. To find this, use the app menu to select Settings or press Cmd/Ctrl + ,.
  2. 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.
  3. Add the following configuration to the JSON file: 
    {
  "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 is required since Windsurf does not support remote MCP servers with authentication natively.
  4. Save the file. It should now prompt you to authenticate with your Clerk account.
  5. 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.

Expected Response Format

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.

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.
  • Claude Desktop via "Integrations" menu / Claude Web: This is not currently supported due to an incompatible implementation of an older version of the MCP spec. We hope this will be resolved in the future.

Troubleshooting

If you encounter issues connecting your MCP client:

  1. Authentication fails: Ensure Dynamic client registration is enabled in your Clerk OAuth Applications settings.
  2. Connection refused: Verify your MCP server is running and accessible at the specified URL.
  3. HTTPS errors: Make sure you're using HTTPS URLs in production environments.
  4. 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?
Edit this page on GitHub

Last updated on