Building a Production-Ready Remote MCP Server with OAuth 2.0 & PKCE

+--------------------------------------------------------------------------+ | LOCALHOST MCP (stdio) | | Desktop Client (Claude/Cursor) ---> Spawn local process (node server.js) | | - Runs only on your local machine | | - Hardcoded credentials in a local .env file | | - Single-user: No concept of who is logged in | +--------------------------------------------------------------------------+ VS. +--------------------------------------------------------------------------+ | REMOTE PRODUCTION MCP (HTTP / SSE / Cloud) | | AI Client (Desktop, Web, Agents) ---> Internet ---> Cloud Web Server | | - Deployed on your favorite cloud (DigitalOcean, AWS, Render, Fly.io) | | - Multi-tenant: Alice sees Alice's team tasks; Bob sees Bob's tasks | | - Users authenticate via browser login with their own credentials | | - Client apps receive short-lived tokens, never raw passwords | +--------------------------------------------------------------------------+ 

 +-----------------------------------+ | MCP SERVER | +-----------------+-----------------+ | +--------------------------+--------------------------+ | | | v v v 1. TOOLS 2. RESOURCES 3. PROMPTS "Do something" "Read something" "Guide the conversation" Functions the model Structured reference data Pre-built prompts and can execute (e.g. the model can read (e.g. workflows with arguments create a task, query project specs, schemas, (e.g. generate daily a database). live status). standup summary). 

 HTTP/1.1 401 Unauthorized  WWW-Authenticate: Bearer resource_metadata="https://api.yourdomain.com/.well-known/oauth-protected-resource" 

taskpulse-mcp/ ├── src/ │ ├── auth/ │ │ ├── clientStore.ts # Registry of allowed AI clients (Claude, Cursor, Dynamic) │ │ ├── oauthProvider.ts # Core OAuth 2.1 engine (implements OAuthServerProvider) │ │ ├── types.ts # Session, token, and scope interfaces │ │ └── views/ │ │ └── consentPage.ts # Clean HTML consent & login screen │ ├── db/ │ │ └── taskStore.ts # In-memory or database layer for tasks and users │ ├── server.ts # McpServer: Tools, Resources, and Prompts │ └── index.ts # Express app, Transports (SSE/HTTP), OAuth router ├── package.json └── tsconfig.json 

mkdir taskpulse-mcp && cd taskpulse-mcp npm init -y npm install @modelcontextprotocol/sdk express dotenv zod npm install --save-dev typescript @types/node @types/express ts-node npx tsc --init 

import { randomUUID } from "node:crypto"; import type { OAuthRegisteredClientsStore } from "@modelcontextprotocol/sdk/server/auth/clients.js"; import type { OAuthClientInformationFull } from "@modelcontextprotocol/sdk/shared/auth.js"; export class TaskPulseClientStore implements OAuthRegisteredClientsStore { private clients = new Map<string, OAuthClientInformationFull>(); constructor() { this.seedDefaultClients(); } private seedDefaultClients(): void { const knownClients: OAuthClientInformationFull[] = [ { client_id: "claude-desktop", client_name: "Claude Desktop", redirect_uris: ["http://localhost/callback", "http://127.0.0.1/callback"], token_endpoint_auth_method: "none", // Public client (uses PKCE) response_types: ["code"], grant_types: ["authorization_code", "refresh_token"], client_id_issued_at: Math.floor(Date.now() / 1000), }, { client_id: "cursor-ide", client_name: "Cursor IDE", redirect_uris: ["http://localhost/callback", "http://127.0.0.1/callback", "http://localhost:3000/callback"], token_endpoint_auth_method: "none", response_types: ["code"], grant_types: ["authorization_code", "refresh_token"], client_id_issued_at: Math.floor(Date.now() / 1000), }, ]; for (const client of knownClients) { this.clients.set(client.client_id, client); } } getClient(clientId: string): OAuthClientInformationFull | undefined { return this.clients.get(clientId); } // RFC 7591: Dynamic Client Registration for new AI agents registerClient( clientData: Omit<OAuthClientInformationFull, "client_id" | "client_id_issued_at"> & { client_id?: string; client_id_issued_at?: number; } ): OAuthClientInformationFull { const clientId = clientData.client_id || randomUUID(); const issuedAt = clientData.client_id_issued_at || Math.floor(Date.now() / 1000); const fullClient: OAuthClientInformationFull = { ...clientData, client_id: clientId, client_id_issued_at: issuedAt, token_endpoint_auth_method: clientData.token_endpoint_auth_method || "none", response_types: clientData.response_types || ["code"], grant_types: clientData.grant_types || ["authorization_code", "refresh_token"], }; this.clients.set(clientId, fullClient); return fullClient; } } 

import { randomBytes, randomUUID, createHmac, timingSafeEqual } from "node:crypto"; import type { Response, Request } from "express"; import type { OAuthServerProvider, AuthorizationParams } from "@modelcontextprotocol/sdk/server/auth/provider.js"; import type { OAuthRegisteredClientsStore } from "@modelcontextprotocol/sdk/server/auth/clients.js"; import type { OAuthClientInformationFull, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js"; import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js"; import { InvalidGrantError, InvalidTokenError } from "@modelcontextprotocol/sdk/server/auth/errors.js"; import { TaskPulseClientStore } from "./clientStore.js"; import { renderConsentPage } from "./views/consentPage.js"; export interface UserSession { userId: string; email: string; orgId: string; } export interface AccessTokenPayload { sub: string; email: string; org_id: string; client_id: string; scopes: string[]; iss: string; iat: number; exp: number; } export class TaskPulseOAuthProvider implements OAuthServerProvider { public readonly clientsStore: OAuthRegisteredClientsStore; public readonly issuerUrl: URL; private readonly jwtSecret: string; private pendingSessions = new Map<string, any>(); private authorizationCodes = new Map<string, any>(); private refreshTokens = new Map<string, any>(); constructor(options: { issuerUrl: URL; clientsStore?: OAuthRegisteredClientsStore; jwtSecret?: string }) { this.issuerUrl = options.issuerUrl; this.clientsStore = options.clientsStore || new TaskPulseClientStore(); this.jwtSecret = options.jwtSecret || process.env.JWT_SECRET || "dev-secret-key-change-in-prod"; } // 1. Initial browser hit to /authorize async authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void> { const sessionId = randomUUID(); this.pendingSessions.set(sessionId, { id: sessionId, client, codeChallenge: params.codeChallenge, redirectUri: params.redirectUri, scopes: params.scopes || ["tasks:read", "tasks:write"], state: params.state, createdAt: Date.now(), }); // Cleanup session after 15 minutes setTimeout(() => this.pendingSessions.delete(sessionId), 15 * 60 * 1000); const html = renderConsentPage({ sessionId, clientName: client.client_name || client.client_id, scopes: params.scopes || ["tasks:read", "tasks:write"], }); res.status(200).type("text/html").send(html); } // 2. User submits consent form async handleConsentDecision(req: Request, res: Response): Promise<void> { const { sessionId, action, email, password } = req.body; const session = this.pendingSessions.get(sessionId); if (!session) { res.status(400).send("Session expired. Please try connecting again."); return; } this.pendingSessions.delete(sessionId); if (action === "deny") { const redirectUrl = new URL(session.redirectUri); redirectUrl.searchParams.set("error", "access_denied"); if (session.state) redirectUrl.searchParams.set("state", session.state); res.redirect(302, redirectUrl.href); return; } try { // Authenticate against your database or auth service const user = await this.authenticateUser(email, password); // Create a single-use authorization code const authCode = randomBytes(32).toString("hex"); this.authorizationCodes.set(authCode, { code: authCode, clientId: session.client.client_id, codeChallenge: session.codeChallenge, redirectUri: session.redirectUri, scopes: session.scopes, user, expiresAt: Date.now() + 10 * 60 * 1000, // 10 minutes }); const redirectUrl = new URL(session.redirectUri); redirectUrl.searchParams.set("code", authCode); if (session.state) redirectUrl.searchParams.set("state", session.state); res.redirect(302, redirectUrl.href); } catch (err: any) { const html = renderConsentPage({ sessionId, clientName: session.client.client_name, scopes: session.scopes, errorMessage: err.message || "Invalid email or password", }); this.pendingSessions.set(sessionId, session); res.status(401).type("text/html").send(html); } } // 3. Return stored PKCE challenge for verification async challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string> { const entry = this.authorizationCodes.get(authorizationCode); if (!entry || entry.clientId !== client.client_id || entry.expiresAt < Date.now()) { throw new InvalidGrantError("Invalid or expired authorization code"); } return entry.codeChallenge; } // 4. Exchange code for JWT access token and refresh token async exchangeAuthorizationCode( client: OAuthClientInformationFull, authorizationCode: string, _codeVerifier?: string, redirectUri?: string ): Promise<OAuthTokens> { const entry = this.authorizationCodes.get(authorizationCode); if (!entry || entry.clientId !== client.client_id) { throw new InvalidGrantError("Invalid authorization code"); } if (redirectUri && entry.redirectUri !== redirectUri) { throw new InvalidGrantError("Redirect URI mismatch"); } Source：https://dev.to/danny_odii/building-a-production-ready-remote-mcp-server-with-oauth-20-pkce-493c
My favorites