mcp-oauth-nextjs

# MCP OAuth Next.js Server A sample Model Context Protocol (MCP) server built with Next.js that supports the new [MCP Authorization Specification (2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). This server integrates with external enterprise authorization servers and can be easily deployed on Vercel. ## Features - ✅ **MCP 2025-06-18 Authorization Spec** - Supports the latest authorization specification - ✅ **RFC 9728 Compliance** - OAuth 2.0 Protected Resource Metadata standard - ✅ **External Authorization Server** - Integrates with enterprise OAuth 2.1 servers - ✅ **Streamable HTTP Transport** - MCP endpoint at `/mcp` - ✅ **Protected Resource Metadata** - RFC 9728 compliant metadata at `/.well-known/oauth-protected-resource` - ✅ **Bearer Token Validation** - Validates tokens from external auth servers - ✅ **Vercel Deployment Ready** - Optimized for Vercel deployment - ✅ **Sample Tools** - Includes demo MCP tools for testing ## Architecture This implementation follows the OAuth 2.0 Protected Resource pattern (RFC 9728) where: 1. **External Authorization Server** - Your enterprise OAuth 2.1 server handles authentication 2. **Protected Resource (MCP Server)** - This Next.js app validates tokens and serves MCP requests 3. **Metadata Discovery** - Clients discover auth server details via RFC 9728 standard endpoint 4. **Bearer Token Flow** - Clients include `Authorization: Bearer <token>` headers ## Quick Start 1. **Clone and Install** ```bash git clone <this-repo> cd mcp-oauth-nextjs npm install ``` 2. **Configure Environment** ```bash cp .env.example .env.local ``` Edit `.env.local` with your enterprise authorization server details: ```env OAUTH_ISSUER_URL=https://your-enterprise-auth-server.com MCP_SERVER_NAME=Your Enterprise MCP Server MCP_SERVER_URL=https://your-deployed-url.vercel.app ``` 3. **Run Development Server** ```bash npm run dev ``` 4. **Test the Endpoints** - Protected Resource Metadata: http://localhost:3000/.well-known/oauth-protected-resource - MCP Endpoint: http://localhost:3000/mcp (requires Bearer token) ## Deployment on Vercel 1. **Deploy to Vercel** ```bash npx vercel --prod ``` 2. **Set Environment Variables** In your Vercel dashboard, add: - `OAUTH_ISSUER_URL`: Your enterprise authorization server URL - `MCP_SERVER_NAME`: Display name for your MCP server - `MCP_SERVER_URL`: Your deployed Vercel URL 3. **Verify Deployment** - Visit `https://your-app.vercel.app/.well-known/oauth-protected-resource` - Should return RFC 9728 compliant protected resource metadata ## Enterprise Integration ### Token Validation The server includes a `validateBearerToken()` function in `/app/mcp/route.ts`. Customize this for your enterprise auth server: ```typescript async function validateBearerToken(authorization: string | null): Promise<boolean> { // Implement your token validation logic: // - JWT verification with public keys // - Token introspection API calls // - Local symmetric key validation } ``` ### RFC 9728 Protected Resource Metadata The metadata endpoint (`/.well-known/oauth-protected-resource`) advertises: - **Authorization Servers**: List of trusted OAuth 2.1 authorization servers - **Supported Scopes**: `mcp:read`, `mcp:execute`, `mcp:tools`, `mcp:admin` - **Bearer Methods**: Header-based bearer token presentation - **Resource Information**: Human-readable name and documentation URLs - **Security Features**: Optional mutual-TLS and DPoP support ### Custom Tools Add your enterprise tools in the MCP server setup: ```typescript server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: 'your_enterprise_tool', description: 'Description of your tool', inputSchema: { /* your schema */ }, }, ], }; }); ``` ## API Endpoints | Endpoint | Method | Description | |----------|--------|-------------| | `/.well-known/oauth-protected-resource` | GET | RFC 9728 Protected Resource Metadata | | `/mcp` | POST | MCP streamable HTTP endpoint | ## Environment Variables | Variable | Description | Required | |----------|-------------|----------| | `OAUTH_ISSUER_URL` | Enterprise authorization server URL | Yes | | `MCP_SERVER_NAME` | Display name for MCP server | No | | `MCP_SERVER_VERSION` | Version string | No | | `MCP_SERVER_URL` | Deployed server URL | No | ## Security Notes - All authorization endpoints must use HTTPS in production - Bearer tokens are validated against your enterprise auth server - CORS is configured for MCP client access - No sensitive data is logged or exposed ## Contributing This is a sample implementation. Customize the token validation, add your enterprise tools, and modify the authorization flow as needed for your organization. ## License MIT License - see LICENSE file for details.