Clerk authentication for Next.js 16 (App Router only) with proxy.ts setup, migration from middleware.ts, environment configuration, and MCP server integration.

Links [Clerk Next.js Quickstart](https://clerk.com/docs/nextjs/getting started/quickstart) [Clerk MCP Server Guide](https://clerk.com/docs/nextjs/guides/ai/mcp/build mcp server) [Clerk Next.js SDK Reference](https://clerk.com/docs/reference/nextjs/overview) [clerkMiddleware() Reference](https://clerk.com/docs/reference/nextjs/clerk middleware) [Reading User Data](https://clerk.com/docs/nextjs/guides/users/reading) [Protecting Routes](https://clerk.com/docs/reference/nextjs/clerk middleware) [OAuth Token Verification](https://clerk.com/docs/nextjs/guides/development/verifying oauth access tokens) [Clerk Dashboard](https://dashboard.clerk.com/) [@vercel/mcp adapter](https://github.com/vercel/mcp adapter) [@clerk/mcp tools](https://github.com/clerk/mcp tools) [MCP Example Repository](https://github.com/clerk/mcp nextjs example) Quick Start 1. Install Dependencies (Using pnpm) 2. Create proxy.ts (Next.js 16) The proxy.ts file replaces middleware.ts from Next.js 15. Create it at the root or in /src : 3. Set Environment Variables Create .env.local in your project root: 4. Add ClerkProvider to Layout 5. Run Your App Visit http://localhost:3000 and click "Sign Up" to create your first user. Key Concepts proxy.ts vs middleware.ts Next.js 16 (App Router) : Use proxy.ts for Clerk middleware Next.js ≤15 : Use middleware.ts with identical code (filename only differs) Clerk's clerkMiddleware() function is the same regardless of filename The matcher configuration ensures proper route handling and performance Protecting Routes By default, clerkMiddleware() does not protect routes—all are public. Use auth.protect() to require authentication: Or protect all routes in proxy.ts : Environment Variable Validation Check for required Clerk keys before runtime: Accessing User Data Use Clerk hooks in client components: Or in server components/actions: Migrating from middleware.ts (Next.js 15) to proxy.ts (Next.js 16) Step by Step Migration 1. Rename the file from middleware.ts to proxy.ts (location remains same: root or /src ) 2. Keep the code identical No functional changes needed: 3. Update Next.js version : 4. Verify environment variables are still in .env.local (no changes needed) 5. Test the migration : Troubleshooting Migration If routes aren't protected, ensure proxy.ts is in the correct location (root or /src ) Check that .env.local has all required Clerk keys Clear .next cache if middleware changes don't take effect: rm rf .next && pnpm dev Verify Next.js version is 16.0+: pnpm list next Building an MCP Server with Clerk See [CLERK MCP SERVER SETUP.md](references/CLERK MCP SERVER SETUP.md) for complete MCP server integration. Quick MCP Setup Summary 1. Install MCP dependencies : 2. Create MCP route at app/[transport]/route.ts : 3. Expose OAuth metadata endpoints (see references for complete setup) 4. Update proxy.ts to exclude .well known endpoints: 5. Enable Dynamic Client Registration in [Clerk Dashboard](https://dashboard.clerk.com/~/oauth applications) Best Practices 1. Environment Variable Management Always use .env.local for development (never commit sensitive keys) Validate environment variables on application startup Use NEXT PUBLIC prefix ONLY for non sensitive keys that are safe to expose For production, set environment variables in your deployment platform (Vercel, etc.) 2. Route Protection Strategies 3. MCP Server Security Enable Dynamic Client Registration in Clerk Dashboard Keep .well known endpoints public but protect all MCP tools with OAuth Use acceptsToken: 'oauth token' in auth() to require machine tokens OAuth tokens are free during public beta (pricing TBD) Always verify tokens with verifyClerkToken() before exposing user data 4. Performance & Caching Use clerkClient() for server side user queries (cached automatically) Leverage React Server Components for secure user data access Cache user data when possible to reduce API calls Use @clerk/nextjs hooks only in Client Components ( 'use client' ) 5. Production Deployment Set all environment variables in your deployment platform Use Clerk's production instance keys (not development keys) Test authentication flow in staging environment before production Monitor Clerk Dashboard for authentication errors Keep @clerk/nextjs updated: pnpm update @clerk/nextjs Troubleshooting Issues & Solutions Issue Solution "Missing environment variables" Ensure .env.local has NEXT PUBLIC CLERK PUBLISHABLE KEY and CLERK SECRET KEY Middleware not protecting routes Verify proxy.ts is in root or /src directory, not in app/ Sign in/sign up pages not working Check NEXT PUBLIC CLERK SIGN IN URL and NEXT PUBLIC CLERK SIGN UP URL in .env.local User data returns null Ensure user is authenticated: check userId is not null before calling getUser() MCP server OAuth fails Enable Dynamic Client Registration in Clerk Dashboard OAuth Applications Changes not taking effect Clear .next cache: rm rf .next and restart pnpm dev "proxy.ts" not recognized Verify Next.js version is 16.0+: pnpm list next Common Next.js 16 Gotchas File naming : Must be proxy.ts (not middleware.ts ) for Next.js 16 Location : Place proxy.ts at project root or in /src directory, NOT in app/ Re exports : Config object must be exported from proxy.ts for matcher to work Async operations : clerkMiddleware() is async ready; use await auth.protect() for route protection Debug Mode Enable debug logging: Run with debug: Related Skills [mcp server skills](../mcp server skills/SKILL.md) : General MCP server patterns with Vercel adapter [nextjs16 skills](../nextjs16 skills/SKILL.MD) : Next.js 16 features, breaking changes, and best practices [authjs skills](../authjs skills/SKILL.md) : Alternative authentication using Auth.js (Auth0, GitHub, etc.) Resources [Clerk Documentation](https://clerk.com/docs) [Clerk Support](https://clerk.com/contact/support) [Clerk Discord Community](https://clerk.com/discord) [Clerk Changelog](https://clerk.com/changelog) [Clerk Feedback](https://feedback.clerk.com/roadmap)

clerk-nextjs-skills