apigene/clerk-mcp-server

Clerk MCP Server

A sample Next.js application that demonstrates how to build an MCP (Model Context Protocol) server with Clerk authentication.

Features

• 🔐 Secure MCP server with Clerk OAuth authentication
• 🛠️ Example tool: get-clerk-user-data that retrieves authenticated user information
• 📡 Support for both HTTP and SSE transport protocols
• 🏗️ Built with Next.js 14 and TypeScript
• 📋 OAuth metadata endpoints for MCP compliance

Prerequisites

• Node.js 18+
• A Clerk account (sign up at clerk.com)

Setup

1. Clone and install dependencies:

   npm install
   

2. Set up Clerk:

   • Go to your Clerk Dashboard
   • Create a new application or use an existing one
   • Copy your publishable key and secret key

3. Configure environment variables:

   cp env.example .env.local
   

   Then edit .env.local and add your Clerk keys:

   NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_your_publishable_key_here
   CLERK_SECRET_KEY=sk_test_your_secret_key_here
   

4. Run the development server:

   npm run dev
   

5. Open your browser: Navigate to http://localhost:3000

MCP Server Endpoints

The MCP server is available at the following endpoints:

• HTTP Transport: http://localhost:3000/mcp
• SSE Transport: http://localhost:3000/sse

OAuth Metadata Endpoints

The server exposes the required OAuth metadata endpoints:

• Authorization Server Metadata: http://localhost:3000/.well-known/oauth-authorization-server
• Protected Resource Metadata: http://localhost:3000/.well-known/oauth-protected-resource/mcp

Available Tools

get-clerk-user-data

Retrieves information about the authenticated Clerk user.

Parameters: None

Returns: JSON string containing user data

Example Response:

{
  "id": "user_123",
  "emailAddresses": [...],
  "firstName": "John",
  "lastName": "Doe",
  ...
}

Project Structure

clerk-mcp-server/
├── app/
│   ├── [transport]/
│   │   └── route.ts              # MCP server implementation
│   ├── .well-known/
│   │   ├── oauth-authorization-server/
│   │   │   └── route.ts          # OAuth server metadata
│   │   └── oauth-protected-resource/
│   │       └── mcp/
│   │           └── route.ts      # Protected resource metadata
│   ├── layout.tsx                # Root layout
│   ├── page.tsx                  # Home page
│   └── globals.css               # Global styles
├── middleware.ts                 # Clerk middleware
├── package.json                  # Dependencies
├── next.config.js               # Next.js config
├── tsconfig.json                # TypeScript config
├── env.example                  # Environment variables template
└── README.md                    # This file

Adding Custom Tools

To add your own MCP tools, modify the app/[transport]/route.ts file:

server.tool(
  'your-tool-name',
  'Description of what your tool does',
  {
    // Define your tool parameters here
    paramName: {
      type: 'string',
      description: 'Parameter description'
    }
  },
  async (params, { authInfo }) => {
    // Your tool implementation
    const userId = authInfo!.extra!.userId! as string
    
    // Your logic here...
    
    return {
      content: [{ type: 'text', text: 'Your response' }],
    }
  },
)

Testing with MCP Clients

You can test the MCP server with any MCP-compatible client. The server supports:

• OAuth 2.0 authentication with Clerk
• HTTP and SSE transport protocols
• Standard MCP tool invocation

Deployment

This project can be deployed to Vercel, Netlify, or any other Next.js-compatible hosting platform. Make sure to:

1. Set the environment variables in your hosting platform
2. Configure your Clerk application's allowed origins
3. Update OAuth redirect URLs if needed

Learn More

• Clerk Documentation
• MCP Specification
• Next.js Documentation
• Vercel MCP Adapter

License

MIT