OAuth authorization server for MCP servers

Secure your Model Context Protocol (MCP) servers with Scalekit’s drop-in OAuth 2.1 authorization solution

Scalekit provides a production-ready OAuth 2.1 authorization server that implements the MCP authorization specification. This guide shows you how to integrate OAuth-based authentication and authorization into your MCP server with minimal code changes.

Why use Scalekit OAuth for MCP servers?

Identity-scoped access: Restrict each token to a specific user or agent.
Granular permissions: Control exactly which tools and data each client can access using fine-grained scopes.
OAuth 2.1 compliance: Rely on a modern, secure, and widely adopted authorization standard.
Comprehensive audit trails: Track who accessed what, when, and with which permissions.

For a deeper explanation of why an OAuth layer is essential for remote MCP servers, read the MCP authorization overview.

How it works

The Scalekit OAuth authorization server and your MCP server work together to secure access and enforce permissions.

Scalekit OAuth authorization server

Acts as the identity provider for your MCP server. It:

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.

Getting started

Prerequisites

Before you begin, ensure you have:

Access to your Scalekit account and the API credentials. If you don’t have a Scalekit account yet, you can signup here.
Installed Scalekit SDK into your project

Node.js
Python

npm install @scalekit-sdk/node

pip install scalekit-sdk-python

Step 1: Register your MCP server

In the Scalekit dashboard, navigate to MCP servers and click Add MCP server. Configure your server with the following settings:

MCP server registration

Basic configuration:

Server name: A display name that users will see during authorization (e.g., “My AI Assistant”)
Resource identifier: Your MCP server’s unique identifier, typically your server’s URL (e.g., https://mcp.yourapp.com). Access tokens minted by Scalekit will have the resource identifier as aud claim.

Access control settings:

Allow dynamic client registration — Enables MCP clients to register automatically without manual approval. For security reasons, Scalekit ensures that any client that registers via DCR has to implement PKCE-based OAuth 2.1 flow to prevent authorization code interception attacks.

Token configuration:

Access token lifetime: Recommended 300-3600 seconds (5 minutes to 1 hour)

Authentication Provider:

Use Scalekit: If you are already using Scalekit to power authentication for your other resources like web application, mobile application, API etc, you can continue to use Scalekit as the authentication provider for your MCP server too.
Use your own authentication provider: If you are using any other authentication provider like Microsoft Entra, Google Workspace, AWS Cognito, Auth0, Keycloak etc, you can configure Scalekit to integrate with your existing auth system to validate user identity.

Step 2: Implement resource metadata discovery

Once you have added your MCP server in the Scalekit dashboard, you will be presented with the protected resource metadata information that you can copy directly from the Scalekit Dashboard and implement in your MCP Server.

MCP clients discover your authorization server through the OAuth 2.0 protected resource metadata endpoint.

Resource Metadata Information

Below is the code sample to implement resource metadata discovery in your MCP Server:

Node.js
Python

// OAuth Protected Resource Metadata endpoint - Required for MCP client discovery
// This endpoint provides metadata about your OAuth protected resource, including supported scopes and token types.
// Replace the placeholder URL with the actual authorization server URL from your Scalekit dashboard.
// Example: https://yourapp.scalekit.com/.well-known/oauth-protected-resource
app.get('/.well-known/oauth-protected-resource', (req, res) => {
  res.json({
    "authorization_servers": [
      "https://<SCALEKIT_ENVIRONMENT_URL>/resources/res_82829009141891595"
    ],
    "bearer_methods_supported": [
      "header"
    ],
    "resource": "https://mcp.yourapp.com",
    "resource_documentation": "https://mcp.yourapp.com/docs",
    "scopes_supported": ["weather:read", "weather:write"]
  });
});

5 collapsed lines
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/res_82829009141891595"
        ],
        "bearer_methods_supported": [
            "header"
        ],
        "resource": "https://mcp.yourapp.com",
        "resource_documentation": "https://mcp.yourapp.com/docs",
        "scopes_supported": ["weather:read", "weather:write"]
    })

Description of the OAuth Protected Resource Metadata:

Field	Description
`resource`	The identifier of the resource server. This is the unique identifier of your MCP Server. Every token that Scalekit issues will have this value as `aud` claim.
`authorization_servers`	A list of authorization servers that are trusted by the resource server. MCP Clients use this information to discover more about the authorization server capability by fetching the authorization server.
`bearer_methods_supported`	A list of methods that are supported for bearer tokens. MCP Clients send the OAuth token as `Authorization: Bearer <token>` header.
`resource_documentation`	A URL to the documentation of the resource server.
`scopes_supported`	A list of scopes that are supported by the resource server. MCP Clients use this information to determine which scopes that they would like the token for as part of the OAuth authorize request.

Step 3: Validate Bearer Token in your MCP Server

Your MCP server needs to validate whether all the incoming requests have a valid access token. Below is a sample middleware implementation if you are using expressjs for implementing your MCP Server.

You can use Scalekit SDKs (across Node.js, Java, GoLang, Python) to determine whether the token is valid or not and whether the token has appropriate claim values like aud, iss, exp, iat, scope etc.

Node.js
Python


10 collapsed lines
1
import { Scalekit, TokenValidationOptions } from '@scalekit-sdk/node';
2
import { NextFunction, Request, Response } from 'express';
3

4
// Initialize Scalekit client with environment credentials
5
const scalekit = new Scalekit(
6
  '<SCALEKIT_ENVIRONMENT_URL>',
7
  '<SCALEKIT_CLIENT_ID>',
8
  '<SCALEKIT_CLIENT_SECRET>'
9
);
10

11
// Resource configuration
12
const RESOURCE_ID = 'https://your-mcp-server.com';
13
const METADATA_ENDPOINT = 'https://your-mcp-server.com/.well-known/oauth-protected-resource';
14

15
// WWW-Authenticate header for unauthorized responses
16
export const WWWHeader = {
17
  HeaderKey: 'WWW-Authenticate',
18
  HeaderValue: `Bearer realm="OAuth", resource_metadata="${METADATA_ENDPOINT}"`
19
};
20

21
export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
22
  try {
23
    // Allow public access to well-known endpoints for metadata discovery
24
    if (req.path.includes('.well-known')) {
25
      return next();
26
    }
27

28
    // Extract Bearer token from Authorization header
29
    const authHeader = req.headers['authorization'];
30
    const token = authHeader?.startsWith('Bearer ')
31
      ? authHeader.split('Bearer ')[1]?.trim()
32
      : null;
33

34
    if (!token) {
35
      throw new Error('Missing or invalid Bearer token');
36
    }
37

38
    // Validate token against configured resource audience
39
    await scalekit.validateToken(token, {
40
      audience: [RESOURCE_ID]
41
    });
42

43
    next();
44
  } catch (err) {
45
    return res
46
      .status(401)
47
      .set(WWWHeader.HeaderKey, WWWHeader.HeaderValue)
48
      .end();
49
  }
50
}
51

52
// Apply authentication middleware to all MCP endpoints
53
app.use('/', authMiddleware);


10 collapsed lines
1
from scalekit import ScalekitClient
2
from scalekit.common.scalekit import TokenValidationOptions
3

4
# Initialize Scalekit client with your environment credentials
5
scalekit_client = ScalekitClient(
6
  '<SCALEKIT_ENVIRONMENT_URL>',
7
  '<SCALEKIT_CLIENT_ID>',
8
  '<SCALEKIT_CLIENT_SECRET>'
9
)
10

11
# Method 1: validate_access_token - Returns boolean (True/False)
12
# Use this method when you only need to verify token validity without detailed error information.
13
# This approach is suitable for simple authorization checks where you don't need token claims.
14
def validate_token_with_issuer_audience(token: str) -> bool:
15
    """
16
    Validates a token and returns True if valid, False otherwise.
17

18
    :param token: The token to validate
19
    :return: True if token is valid, False otherwise
20
    """
21
    options = TokenValidationOptions(
22
        issuer="<SCALEKIT_ENVIRONMENT_URL>",
23
        audience=["your-api-audience"]
24
    )
25

26
    try:
27
        is_valid = scalekit_client.validate_access_token(token, options=options)
28
        return is_valid
29
    except Exception as ex:
30
        print(f"Token validation failed: {ex}")
31
        return False
32

33
# Method 2: validate_token - Returns token claims/payload
34
# Use this method when you need access to token claims (user info, scopes, etc.) or detailed error information.
35
# This approach is suitable for authorization that requires specific user context or scope validation.
36
def validate_token_and_get_claims(token: str) -> dict:
37
    """
38
    Validates a token with specific audience and raises exception on failure.
39

40
    :param token: The token to validate
41
    :raises: ScalekitValidateTokenFailureException if validation fails
42
    """
43
    options = TokenValidationOptions(
44
        issuer="<SCALEKIT_ENVIRONMENT_URL>",
45
        audience=["your-api-audience"],
46
        required_scopes=["read:users", "write:users"]  # Optional: validate specific scopes for finer access control
47
    )
48

49
    scalekit_client.validate_token(token, options=options)

Step 4: (Optional) Implement Scope-based authorization at the tool execution level

Implement scope validation at the MCP tool execution level to ensure that the tool is only executed if the user has authorized the MCP client for the required scope.

Node.js
Python

1
// Validate token has required scope for this specific tool execution
2
try{
3
    await scalekit.validateToken(
4
      token, {
5
        audience: [RESOURCE_ID],
6
        requiredScopes: [scope]
7
        }
8
      );
9
} catch(error){
10
    return res.status(403).json({
11
        error: 'insufficient_scope',
12
        error_description: `Required scope: ${scope}`,
13
        scope: scope
14
  });
15
}

1
# Validate token has required scope for this specific tool execution
2
try:
3
    scalekit_client.validate_access_token(
4
        token,
5
        options=TokenValidationOptions(
6
            audience=[RESOURCE_ID],
7
            required_scopes=[scope]
8
        )
9
    )
10
except ScalekitValidateTokenFailureException as ex:
11
    return {
12
        "error": "insufficient_scope",
13
        "error_description": f"Required scope: {scope}",
14
        "scope": scope
15
    }

Next Steps

Download our sample MCP Server: We have put together a simple MCP server that you can check out and run it locally to test the end to end functionality of a working MCP server complete with authentication and authorization. You can download and execute a sample MCP server implementation from GitHub.