Add OAuth 2.1 authorization to MCP servers

This guide shows you how to add production-ready OAuth 2.1 authorization to your Model Context Protocol (MCP) server using Scalekit. You’ll learn how to secure your MCP server so that only authenticated and authorized users can access your tools through AI hosts like Claude Desktop, Cursor, or VS Code.

See the integration in action

Play

MCP servers expose tools that AI hosts can discover and execute to interact with your resources. For example:

• A sales team member could use Claude Desktop to view customer information, update records, or set follow-up reminders
• A developer could use VS Code or Cursor with a GitHub MCP server to perform everyday GitHub actions through chat
• An autonomous agent could use an MCP server to perform actions such as look up the account details in a CRM system

When you build MCP servers, multiple AI hosts may need to discover and use your server to interact with your resources. Scalekit handles the complex authentication and authorization for you, so you can focus on building better tools and improving functionality.

1. Get Scalekit SDK

   To get started, make sure you have your Scalekit account and API credentials ready. If you haven’t created a Scalekit account yet, you can sign up and get a free account.

   Next, install the Scalekit SDK for your language:

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit-sdk-python

   Use the Scalekit dashboard to register your MCP server and configure MCP hosts (or AI agents following the MCP client protocol) to use Scalekit as the authorization server. The Scalekit SDK validates tokens after users have been authenticated and authorized to access your MCP server.

2. Add MCP server to get drop-in OAuth2.1 authorization server

   In the Scalekit dashboard, go to MCP servers and select Add MCP server.

   

   1. Provide a name for your MCP server to help you identify it easily. This name appears on the Consent page that MCP hosts display to users when authorizing access to your MCP server.
   2. Enable dynamic client registration for MCP hosts. This allows MCP hosts to automatically register with Scalekit (and your authorization server), eliminating the need for manual registration and making it easier for users to adopt your MCP server secur.
   3. Click Save to register the server.

   When you save, Scalekit displays the OAuth-protected resource metadata. Copy this JSON—you’ll use it to implement the discovery endpoint, up next.

   Advanced settings

   • Server URL: Your MCP server’s unique identifier, typically your server’s URL (e.g., https://mcp.yourapp.com). This is an optional field. If not provided, Scalekit will use the generated resource_id as the resource identifier. If provided, access tokens minted by Scalekit will have the resource identifier as aud claim along with the Scalekit generated resource_id.

   Using FastMCP?

   If you’re using FastMCP, you must provide a resource identifier. For a server running at https://mcp.example.com/mcp, register https://mcp.example.com/ as the resource identifier. FastMCP appends /mcp automatically, so use the base URL with a trailing slash only.

   • Access token lifetime: Recommended 300-3600 seconds (5 minutes to 1 hour)
   • Scopes: Define the permissions your MCP server needs, such as usr:read or usr:write. These scopes are pre-approved when users authenticate to use your MCP server, streamlining the authorization process.

3. Let MCP clients discover your OAuth2.1 authorization server

   MCP protocol directs any MCP client to discover your OAuth2.1 authorization server by calling a public endpoint on your MCP server. This endpoint is called .well-known/oauth-protected-resource and your MCP server must host this endpoint.

   

   Copy the resource metadata JSON from Dashboard > MCP Servers > Your server > Metadata JSON and implement it in your .well-known/oauth-protected-resource endpoint. The authorization_servers field contains your Scalekit resource identifier, which clients use to initiate the OAuth flow.

   Node.js

   // MCP client discovery endpoint
   // Use case: Allow MCP clients to discover OAuth authorization server configuration
   app.get('/.well-known/oauth-protected-resource', (req, res) => {
     res.json({
       // From Scalekit dashboard > MCP servers > Your server > Metadata JSON
       "authorization_servers": [
         "https://<SCALEKIT_ENVIRONMENT_URL>/resources/<YOUR_RESOURCE_ID>"
       ],
       "bearer_methods_supported": [
         "header"  // Bearer token in Authorization header
       ],
       "resource": "https://mcp.yourapp.com",  // Your MCP server URL
       "resource_documentation": "https://mcp.yourapp.com/docs", // A URL to the documentation of the resource server
       "scopes_supported": ["todo:read", "todo:write"]  // Dashboard-configured scopes
     });
   });

   Python

    from fastapi import FastAPI
    from fastapi.responses import JSONResponse
   
    app = FastAPI()
   
    # OAuth Protected Resource Metadata endpoint - Required for MCP client discovery
    # Copy the actual authorization server URL and metadata from your Scalekit dashboard.
    # The values shown here are examples - replace with your actual configuration.
    @app.get("/.well-known/oauth-protected-resource")
    async def get_oauth_protected_resource():
        return JSONResponse({
            "authorization_servers": [
                "https://<SCALEKIT_ENVIRONMENT_URL>/resources/<YOUR_RESOURCE_ID>"
            ],
            "bearer_methods_supported": [
                "header"
            ],
            "resource": "https://mcp.yourapp.com",
            "resource_documentation": "https://mcp.yourapp.com/docs",
            "scopes_supported": ["todo:read", "todo:write"]
        })

4. Validate all MCP client requests have a valid access token

   Your MCP server should validate that all incoming requests contain a valid access token. Leverage Scalekit SDKs to validate tokens and verify essential claims such as aud (audience), iss (issuer), exp (expiration), iat (issued at), and scope (permissions).

   Node.js

   auth-config.js

   10 collapsed lines
   import { Scalekit } from '@scalekit-sdk/node';
   
   // Initialize Scalekit client with environment credentials
   // Reference installation guide for client setup details
   const scalekit = new Scalekit(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET
   );
   
   // Resource configuration
   // Get these values from Scalekit dashboard > MCP servers > Your server
   // For FastMCP: Use base URL with trailing slash (e.g., https://mcp.example.com/)
   const RESOURCE_ID = 'https://your-mcp-server.com';
   const METADATA_ENDPOINT = 'https://your-mcp-server.com/.well-known/oauth-protected-resource';
   
   // WWW-Authenticate header for unauthorized responses
   // This helps clients understand how to authenticate properly
   export const WWWHeader = {
     HeaderKey: 'WWW-Authenticate',
     HeaderValue: `Bearer realm="OAuth", resource_metadata="${METADATA_ENDPOINT}"`
   };

   Python

   auth_config.py

   12 collapsed lines
   from scalekit import ScalekitClient
   from scalekit.common.scalekit import TokenValidationOptions
   import os
   
   # Initialize Scalekit client with environment credentials
   # Reference installation guide for client setup details
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET")
   )
   
   # Resource configuration
   # Get these values from Scalekit dashboard > MCP servers > Your server
   # For FastMCP: Use base URL with trailing slash (e.g., https://mcp.example.com/)
   RESOURCE_ID = "https://your-mcp-server.com"
   METADATA_ENDPOINT = "https://your-mcp-server.com/.well-known/oauth-protected-resource"
   
   # WWW-Authenticate header for unauthorized responses
   # This helps clients understand how to authenticate properly
   WWW_HEADER = {
       "WWW-Authenticate": f'Bearer realm="OAuth", resource_metadata="{METADATA_ENDPOINT}"'
   }

   Extract the Bearer token from incoming MCP client requests. MCP clients send tokens in the Authorization: Bearer <token> header format.

   Node.js

   // Extract Bearer token from Authorization header
   // Use case: Validate requests from AI hosts like Claude Desktop, Cursor, or VS Code
   const authHeader = req.headers['authorization'];
   const token = authHeader?.startsWith('Bearer ')
     ? authHeader.split('Bearer ')[1]?.trim()
     : null;
   
   if (!token) {
     throw new Error('Missing or invalid Bearer token');
   }

   Python

   # Extract Bearer token from Authorization header
   # Use case: Validate requests from AI hosts like Claude Desktop, Cursor, or VS Code
   auth_header = request.headers.get("Authorization", "")
   token = None
   if auth_header.startswith("Bearer "):
       token = auth_header.split("Bearer ")[1].strip()
   
   if not token:
       raise ValueError("Missing or invalid Bearer token")

   Validate the token against your configured resource audience to ensure it was issued for your specific MCP server. The resource identifier must match the Server URL you registered earlier.

   Node.js

   Validate token

   // Security: Validate token against configured resource audience
   // This ensures the token was issued for your specific MCP server
   await scalekit.validateToken(token, {
     audience: [RESOURCE_ID]
   });

   Python

   Validate token

    # Method 1: validate_access_token - Returns boolean (True/False)
    # Use this method when you only need to verify token validity without detailed error information.
    # This approach is suitable for simple authorization checks where you don't need token claims.
    def validate_token_with_issuer_audience(token: str) -> bool:
        """
        Validates a token and returns True if valid, False otherwise.
   
        :param token: The token to validate
        :return: True if token is valid, False otherwise
        """
        options = TokenValidationOptions(
            issuer="<SCALEKIT_ENVIRONMENT_URL>",
            audience=["your-api-audience"]
        )
   
        try:
            is_valid = scalekit_client.validate_access_token(token, options=options)
            return is_valid
        except Exception as ex:
            print(f"Token validation failed: {ex}")
            return False
   
    # Method 2: validate_token - Returns token claims/payload
    # Use this method when you need access to token claims (user info, scopes, etc.) or detailed error information.
    # This approach is suitable for authorization that requires specific user context or scope validation.
    def validate_token_and_get_claims(token: str) -> dict:
        """
        Validates a token with specific audience and raises exception on failure.
   
        :param token: The token to validate
        :raises: ScalekitValidateTokenFailureException if validation fails
        """
        options = TokenValidationOptions(
            issuer="<SCALEKIT_ENVIRONMENT_URL>",
            audience=["<YOUR_MCP_AUDIENCE>"],
            required_scopes=["todo:read", "todo:write"]  # Optional: validate specific scopes for finer access control
        )
   
        scalekit_client.validate_token(token, options=options)

   Complete middleware implementation

   Combine token extraction and validation into a complete authentication middleware that protects all your MCP endpoints.

   Node.js

   import { Scalekit } from '@scalekit-sdk/node';
   import { NextFunction, Request, Response } from 'express';
   
   const scalekit = new Scalekit(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET
   );
   
   const RESOURCE_ID = 'https://your-mcp-server.com';
   const METADATA_ENDPOINT = 'https://your-mcp-server.com/.well-known/oauth-protected-resource';
   
   export const WWWHeader = {
     HeaderKey: 'WWW-Authenticate',
     HeaderValue: `Bearer realm="OAuth", resource_metadata="${METADATA_ENDPOINT}"`
   };
   
   export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
     try {
       // Security: Allow public access to well-known endpoints for metadata discovery
       // This enables MCP clients to discover your OAuth configuration
       if (req.path.includes('.well-known')) {
         return next();
       }
   
       // Extract Bearer token from Authorization header
       const authHeader = req.headers['authorization'];
       const token = authHeader?.startsWith('Bearer ')
         ? authHeader.split('Bearer ')[1]?.trim()
         : null;
   
       if (!token) {
         throw new Error('Missing or invalid Bearer token');
       }
   
       // Security: Validate token against configured resource audience
       await scalekit.validateToken(token, {
         audience: [RESOURCE_ID]
       });
   
       next();
     } catch (err) {
       // Return proper OAuth 2.0 error response with WWW-Authenticate header
       return res
         .status(401)
         .set(WWWHeader.HeaderKey, WWWHeader.HeaderValue)
         .end();
     }
   }
   
   // Apply authentication middleware to all MCP endpoints
   app.use('/', authMiddleware);

   Python

   from scalekit import ScalekitClient
   from scalekit.common.scalekit import TokenValidationOptions
   from fastapi import Request, HTTPException, status
   from fastapi.responses import Response
   import os
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET")
   )
   
   RESOURCE_ID = "https://your-mcp-server.com"
   METADATA_ENDPOINT = "https://your-mcp-server.com/.well-known/oauth-protected-resource"
   
   # WWW-Authenticate header for unauthorized responses
   WWW_HEADER = {
       "WWW-Authenticate": f'Bearer realm="OAuth", resource_metadata="{METADATA_ENDPOINT}"'
   }
   
   async def auth_middleware(request: Request, call_next):
       # Security: Allow public access to well-known endpoints for metadata discovery
       if request.url.path.startswith("/.well-known"):
           return await call_next(request)
   
       # Extract Bearer token from Authorization header
       auth_header = request.headers.get("Authorization", "")
       token = None
       if auth_header.startswith("Bearer "):
           token = auth_header.split("Bearer ")[1].strip()
   
       if not token:
           raise HTTPException(
               status_code=status.HTTP_401_UNAUTHORIZED,
               headers=WWW_HEADER
           )
   
       # Security: Validate token against configured resource audience
       try:
           options = TokenValidationOptions(
               issuer=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
               audience=[RESOURCE_ID]
           )
           scalekit_client.validate_token(token, options=options)
       except Exception:
           raise HTTPException(
               status_code=status.HTTP_401_UNAUTHORIZED,
               headers=WWW_HEADER
           )
   
       return await call_next(request)
   
   # Apply authentication middleware to all MCP endpoints
   app.middleware("http")(auth_middleware)

5. Implement scope-based tool authorization Optional

   Add scope validation at the MCP tool execution level to ensure tools are only executed when the user has authorized the MCP client with the required permissions. This provides fine-grained access control and follows the principle of least privilege.

   Node.js

   // Security: Validate token has required scope for this specific tool execution
   // Use case: Ensure users only have access to authorized MCP tools
   try {
       await scalekit.validateToken(
         token, {
           audience: [RESOURCE_ID],
           requiredScopes: [scope]
           }
         );
   } catch(error) {
       // Return OAuth 2.0 compliant error for insufficient scope
       return res.status(403).json({
           error: 'insufficient_scope',
           error_description: `Required scope: ${scope}`,
           scope: scope
     });
   }

   Python

   # Security: Validate token has required scope for this specific tool execution
   # Use case: Ensure users only have access to authorized MCP tools
   try:
       scalekit_client.validate_access_token(
           token,
           options=TokenValidationOptions(
               audience=[RESOURCE_ID],
               required_scopes=[scope]
           )
       )
   except ScalekitValidateTokenFailureException as ex:
       # Return OAuth 2.0 compliant error for insufficient scope
       return {
           "error": "insufficient_scope",
           "error_description": f"Required scope: {scope}",
           "scope": scope
       }

   Fine-grained access control

   Implement scope-based authorization to provide granular control over which tools and resources each client can access. This improves security by limiting potential damage from compromised tokens and ensures users only access appropriate MCP functionality.

6. Enable additional authentication methods

   Beyond the OAuth 2.1 authorization you’ve implemented, you can enable additional authentication methods that work seamlessly with your MCP server’s token validation:

   Enterprise SSO

   Enable organizations to authenticate through their identity providers (Okta, Azure AD, Google Workspace). Your MCP server continues validating tokens the same way, while Scalekit handles:

   • Centralized access control through existing enterprise identity systems
   • Single sign-on experience for organization members
   • Compliance with corporate security policies

   Organization owned domains

   Authentication through Enterprise SSO for MCP users requires the organization administrators to register the domain their organization owns with Scalekit through the admin portal.

   Social logins

   Allow users to authenticate via Google, GitHub, Microsoft, and other social providers. Your existing token validation logic remains unchanged while providing:

   • Quick onboarding for individual users
   • Familiar authentication experience
   • Reduced friction for personal and small team use cases

   These authentication methods require no changes to your MCP server implementation—you continue validating tokens exactly as shown in the previous steps.

   Bring your own auth allows you to use your own authentication system to authenticate users to your MCP server.

Your MCP server now has production-ready OAuth 2.1 authorization! You’ve successfully implemented a secure authorization flow that protects your MCP tools and ensures only authenticated users can access them through AI hosts.

Try the demo: Download and run our sample MCP server with authentication already configured to see the complete integration in action.

Production deployment checklist

Before deploying to production, ensure you:

• Configure proper CORS policies for your MCP server endpoints
• Set up monitoring and logging for authorization events
• Use HTTPS for all communications
• Store client secrets securely using environment variables or secret management systems
• Configure appropriate token lifetimes based on your security requirements
• Test with various AI hosts (Claude Desktop, Cursor, VS Code) to verify compatibility

In summary,

Scalekit OAuth authorization server

Acts as the identity provider for your MCP server.

• Authenticates users and agents
• Issues access tokens with fine-grained scopes
• Manages OAuth 2.1 flows (authorization code, client credentials)
• Supports dynamic client registration for easy onboarding

Your MCP server

Validates incoming access tokens and enforces the permissions encoded in each token. Only requests with valid, authorized tokens are allowed.

This separation of responsibilities ensures a clear boundary: Scalekit handles identity and token issuance, while your MCP server focuses on business logic of executing the actual tool calls.