Provides OAuth 2.0 authentication flow for securing MCP tools, allowing users to authenticate with their existing Clerk accounts and access protected resources
Enables deployment of the MCP server on Cloudflare's edge network for global distribution and serverless execution
Supports integration with React Router applications, allowing implementation of MCP authentication flows within existing React applications
Clerk MCP Server Template
A production-ready template for building Model Context Protocol (MCP) servers with Clerk authentication on Cloudflare Workers. This template provides everything you need to create secure, authenticated MCP tools that integrate with your existing Clerk-powered applications.
Features
- ✅ Clerk Authentication Integration - Complete OAuth 2.0 flow with Clerk
- ✅ Cloudflare Workers - Serverless edge computing with global distribution
- ✅ Durable Objects - Persistent MCP session state management
- ✅ KV Storage - Temporary OAuth session storage
- ✅ Security - HMAC-signed state parameters and automatic token refresh
- ✅ TypeScript - Full type safety throughout the codebase
- ✅ Example Tools - Ready-to-use example MCP tools
- ✅ Development Tools - ESLint, Prettier, and MCP Inspector integration
Why This Template?
This template bridges your existing Clerk-authenticated application with Claude AI through MCP tools. Perfect for:
- SaaS Applications: Give Claude access to your user data and business logic
- Customer Support: Let Claude query your systems with proper user context
- Data Analysis: Provide Claude with authenticated access to your APIs
- Workflow Automation: Create secure, user-specific automations
Quick Start
1. Prerequisites
- Node.js 22.x or later
- A Clerk account with API keys
- A Cloudflare account with Workers enabled
- An existing application using Clerk for authentication
2. Use This Template
3. Configure Environment Variables
Copy the example environment file:
Update .dev.vars
with your Clerk keys and app URL:
Important:
APP_URL
should point to your existing Clerk-authenticated application where you'll implement the MCP auth flow.
4. Create KV Namespace
Create a KV namespace for OAuth session storage:
Update the id
in wrangler.jsonc
with the generated namespace ID.
5. Update Configuration
wrangler.jsonc
:
- Change
name
from"your-mcp-server"
to your desired worker name - Update the KV namespace ID with the one generated above
src/index.ts
:
- Update the server name and version in the
McpServer
constructor - Replace example tools with your own (see examples below)
6. Start Development
The server will be available at http://localhost:8788
Architecture
Authentication Flow
- MCP Client connects to
/sse
endpoint - OAuth redirect to
/authorize
endpoint - User authentication via Clerk (you implement this part)
- Token exchange at
/callback
endpoint - Session creation in Durable Objects
- MCP tools become available with authenticated context
Integrating with Your Application
Step 1: Add MCP Authentication Route
Create an authentication route in your existing Clerk application at
/auth/mcp
. This route handles the OAuth flow initiated by the MCP server.
React Router v7 (Framework Mode) Example
This example shows integration with React Router v7 in framework mode (formerly Remix), but you can adapt it to Next.js, Express, or any framework.
app/routes/auth.mcp.tsx
:
Step 2: Create API Endpoints
Add protected API endpoints in your application that the MCP server can call with authenticated requests.
app/routes/api.users.tsx
:
Step 3: Customize MCP Tools
Replace the example tools in src/index.ts
with your own:
Configuration Reference
Environment Variables
Variable | Description | Required |
---|---|---|
CLERK_SECRET_KEY | Your Clerk secret key | ✅ |
CLERK_PUBLISHABLE_KEY | Your Clerk publishable key | ✅ |
APP_URL | Your application URL | ✅ |
Add your own application-specific environment variables to the Env
interface
in src/types.ts
.
Clerk JWT Templates
Create a JWT template in your Clerk Dashboard for token generation:
- Go to JWT Templates in your Clerk Dashboard
- Create a new template (e.g., "mcp-server")
- Update the template name in
src/index.ts
:
Development
Available Scripts
Testing with MCP Inspector
- Start the development server:
npm run dev
- Open MCP Inspector
- Set transport type to SSE
- Connect to
http://localhost:8788/sse
- Complete the authentication flow
- Test your tools
Deployment
1. Set Production Secrets
2. Create Production KV Namespace
Update the production KV namespace ID in wrangler.jsonc
.
3. Deploy and Configure
Add your deployed server to Claude Desktop MCP configuration:
Project Structure
Security Considerations
- OAuth 2.0 ensures secure authentication flow
- HMAC signatures protect state parameters from tampering
- Automatic token refresh handles session expiration
- Session cleanup removes expired OAuth sessions
- Secure headers include proper CORS and authentication headers
Troubleshooting
Common Issues
Authentication fails:
- Verify Clerk API keys are correct
- Ensure your authentication route is implemented
- Check that JWT template exists in Clerk Dashboard
KV namespace errors:
- Verify namespace ID in
wrangler.jsonc
- Ensure namespace is created and bound
Tools not working:
- Check that user is authenticated
- Verify API endpoints are correct
- Review Cloudflare Workers logs
Debugging
Contributing
- Fork this repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Commit your changes:
git commit -m 'Add amazing feature'
- Push to the branch:
git push origin feature/amazing-feature
- Open a Pull Request
Resources
- Model Context Protocol Specification
- Clerk Authentication Documentation
- Cloudflare Workers Documentation
- Cloudflare MCP Examples
- React Router v7 Documentation
License
MIT License - see LICENSE file for details.
This server cannot be installed
A production-ready template for building Model Context Protocol servers with Clerk authentication on Cloudflare Workers, allowing AI assistants to securely access user data and business logic in Clerk-authenticated applications.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server implementation that runs on Cloudflare Workers, providing tool integration for AI assistants like Claude with OAuth login capability.Last updated -14TypeScript
- -securityFlicense-qualityA deployable Model Context Protocol server on Cloudflare Workers that operates without authentication, allowing connection to AI assistants like Claude Desktop and Cloudflare AI Playground.Last updated -TypeScript
- -securityFlicense-qualityA tool for deploying an authentication-free Model Context Protocol server on Cloudflare Workers that can be connected to AI clients like Claude Desktop or the Cloudflare AI Playground.Last updated -TypeScript
- -securityFlicense-qualityA deployment solution for a remote Model Context Protocol server on Cloudflare Workers that doesn't require authentication, allowing users to create and use custom AI tools with Claude and other MCP clients.Last updated -TypeScript