MCP Authentication: MCP-specific authentication patterns and integration guides with OAuth 2.1 and Dynamic Client Registration
---
# DOCUMENT BOUNDARY
---
# Overview: MCP server authentication
> Secure your Model Context Protocol (MCP) servers with Scalekit's drop-in OAuth 2.1 authorization solution
Model Context Protocol (MCP) is an open standard that gives AI apps a consistent, secure way to connect to external tools and data sources. A helpful way to picture it is USB‑C for AI integrations: instead of building a custom connector for every service, MCP provides one interface that works across different models, platforms, and backends. That makes it much easier to build agent-style apps that can actually do work, but it also makes authorization a bigger deal, because once an agent can act on your behalf, you need clear, tight control over what it can access and what actions it’s allowed to take. At its core, MCP follows a client-server architecture where a host application can connect to multiple servers: * **MCP hosts**: AI applications like Claude Desktop, IDEs, or custom AI tools that need to access external resources * **MCP clients**: Protocol clients that maintain connections between hosts and servers * **MCP servers**: Lightweight programs that expose specific capabilities (tools, data, or services) through the standardized protocol * **Data sources**: Local files, databases, APIs, and services that MCP servers can access This architecture enables a ecosystem where AI models can seamlessly integrate with hundreds of different services without requiring custom code for each integration. ## The path to secure MCP: OAuth 2.1 integration [Section titled “The path to secure MCP: OAuth 2.1 integration”](#the-path-to-secure-mcp-oauth-21-integration) Recognizing these challenges, the MCP specification evolved to incorporate robust authorization mechanisms. The Model Context Protocol provides authorization capabilities at the transport level, enabling MCP clients to make requests to restricted MCP servers on behalf of resource owners. The **MCP specification chose OAuth 2.1 as its authorization framework** for several compelling reasons | | | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Industry standard | OAuth 2.1 is a well-established, widely-adopted standard for delegated authorization, with extensive tooling and ecosystem support. | | Security best practices | OAuth 2.1 incorporates lessons learned from OAuth 2.0, removing deprecated flows and enforcing security measures like PKCE (Proof Key for Code Exchange). | | Flexibility | Supports multiple grant types suitable for different MCP use cases: **Authorization code**: When AI agents act on behalf of human users **Client credentials**: For machine-to-machine integrations | | Ecosystem compatibility | Works with existing identity providers and authorization servers, making it easier for enterprises to integrate MCP into their existing security infrastructure. | This authorization mechanism is based on established specifications listed below, but implements a selected subset of their features to ensure security and interoperability while maintaining simplicity: * **OAuth 2.1**: Core authorization framework with enhanced security * **OAuth 2.0 Authorization Server Metadata (RFC8414)**: Standardized server discovery * **OAuth 2.0 Dynamic Client Registration Protocol (RFC7591)**: Automatic client registration * **OAuth 2.0 Protected Resource Metadata (RFC9728)**: Resource server discovery * **Client ID Metadata Document (CIMD)**: Lets authorization servers fetch client metadata directly from a client-hosted document for authorization ## The authorization flow in practice [Section titled “The authorization flow in practice”](#the-authorization-flow-in-practice) Now let’s zoom in and see how the MCP OAuth 2.1 flow unfolds step-by-step: ### Discovery phase [Section titled “Discovery phase”](#discovery-phase) 1. **MCP client** encounters a protected MCP server 2. **Server** responds with `401 Unauthorized` and `WWW-Authenticate` header pointing to Scalekit Auth Server 3. **Client** discovers Scalekit Auth Server capabilities through metadata endpoints  ### Authorization phase [Section titled “Authorization phase”](#authorization-phase) 4. **Client** registers with Scalekit Auth Server (if using DCR) 5. **Scalekit Auth Server** issues client credentials (if using DCR) 6. **Client** initiates appropriate OAuth flow 7. **User** grants consent (for Authorization Code flow) 8. **Scalekit Auth Server** issues access token with appropriate scopes ### Client registration [Section titled “Client registration”](#client-registration) #### Dynamic client registration [Section titled “Dynamic client registration”](#dynamic-client-registration) MCP clients and authorization servers SHOULD support the OAuth 2.1 Dynamic Client Registration Protocol to allow MCP clients to obtain OAuth client IDs without user interaction. This enables seamless onboarding of new AI agents without manual configuration.  #### Client ID Metadata Document (CIMD) [Section titled “Client ID Metadata Document (CIMD)”](#client-id-metadata-document-cimd) MCP clients SHOULD support the Client ID Metadata Document (CIMD) specification, which allows clients to publish their OAuth client metadata at a well-known URL under their control. This enables authorization servers to automatically retrieve and validate client metadata without requiring an explicit dynamic registration request, simplifying onboarding for new AI agents while maintaining secure, decentralized client configuration.  ### Access phase [Section titled “Access phase”](#access-phase) 9. **Client** includes access token in requests to MCP server 10. **MCP server** validates token and enforces scope-based permissions 11. **Server** processes request and returns response 12. **All interactions** are logged for audit and compliance  ## Key security enhancements in MCP OAuth 2.1 [Section titled “Key security enhancements in MCP OAuth 2.1”](#key-security-enhancements-in-mcp-oauth-21) MCP’s OAuth 2.1 profile reduces a few common risks in the authorization code flow. The key enhancements are: * **Mandatory PKCE**: Clients must use PKCE to help prevent authorization code interception. * **Strict redirect URI validation**: Servers must only allow pre-registered redirect URIs and enforce an exact match to reduce redirect attacks. * **Short-lived tokens**: Authorization servers should issue short-lived access tokens to limit impact if a token leaks. * **Granular scopes**: Use narrow scopes (for example, `todo:read`, `todo:write`) so apps request only what they need and users can understand what they’re granting.
---
# DOCUMENT BOUNDARY
---
# Add OAuth 2.1 authorization to MCP servers
> Secure your Model Context Protocol (MCP) servers with Scalekit's drop-in OAuth 2.1 authorization solution and protect your AI integrations
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. Using a coding agent?Copy MCP prompt 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 [Section titled “Get Scalekit SDK”](#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](https://app.scalekit.com/ws/signup). Next, install the Scalekit SDK for your language: * Node.js
```bash
npm install @scalekit-sdk/node
```
* Python
```sh
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 [Section titled “Add MCP server to get drop-in OAuth2.1 authorization server”](#add-mcp-server-to-get-drop-in-oauth21-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. Enable **Client ID Metadata Document (CIMD)** to allow your authorization server to fetch client metadata from MCP hosts and authorize them automatically. 4. Click **Save** to register the server. Note: If your MCP server is intended for use by public MCP clients such as Claude, Cursor, or VS Code, it is recommended to keep both DCR and CIMD enabled. Clients that support CIMD will use the CIMD flow, while clients that do not yet support CIMD can fall back to Dynamic Client Registration. This ensures your MCP server remains compatible with the widest range of MCP clients while preserving a smooth authorization experience. Toggling DCR or CIMD? If you enable or disable DCR or CIMD, be sure to restart your MCP server. Certain MCP frameworks, like FastMCP, cache authorization server details, and a restart ensures the updated configuration is correctly applied. 3. ## Let MCP clients discover your OAuth2.1 authorization server [Section titled “Let MCP clients discover your OAuth2.1 authorization server”](#let-mcp-clients-discover-your-oauth21-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
```javascript
// 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:///resources/"
],
"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
```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:///resources/"
],
"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 [Section titled “Validate all MCP client requests have a valid access token”](#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). The code in this step expects tokens whose issuer (`iss`) is `/resources/`. If you see the **Resource bound issuer** option on your MCP server in the Scalekit dashboard, your workspace was created before October 21, 2026. Until you enable that option, your tokens carry your environment URL as the issuer, and this code rejects them with a `401` and `unexpected "iss" claim value`. Follow [Migrate to the new MCP spec](/authenticate/mcp/migrate-to-2026-07-28-mcp-spec/) first. If you need any assistance or help, contact . * Node.js auth-config.js
```javascript
1
import { Scalekit } from '@scalekit-sdk/node';
2
3
// Initialize Scalekit client with environment credentials
4
// Reference installation guide for client setup details
5
const scalekit = new Scalekit(
6
process.env.SCALEKIT_ENVIRONMENT_URL,
7
process.env.SCALEKIT_CLIENT_ID,
8
process.env.SCALEKIT_CLIENT_SECRET
9
);
10
11
// Resource configuration
12
// Get these values from Scalekit dashboard > MCP servers > Your server
13
// For FastMCP: Use base URL with trailing slash (e.g., https://mcp.example.com/)
14
const RESOURCE_ID = 'res_123456789'; // Resource ID (res_...) from Dashboard > MCP servers > Your server. Used as the token audience and in the issuer.
15
const METADATA_ENDPOINT = 'https://your-mcp-server.com/.well-known/oauth-protected-resource';
16
17
// WWW-Authenticate header for unauthorized responses
18
// This helps clients understand how to authenticate properly
19
export const WWWHeader = {
20
HeaderKey: 'WWW-Authenticate',
21
HeaderValue: `Bearer realm="OAuth", resource_metadata="${METADATA_ENDPOINT}"`
22
};
```
* Python auth_config.py
```python
1
from scalekit import ScalekitClient
2
from scalekit.common.scalekit import TokenValidationOptions
3
import os
4
5
# Initialize Scalekit client with environment credentials
6
# Reference installation guide for client setup details
7
scalekit_client = ScalekitClient(
8
env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
9
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
10
client_secret=os.getenv("SCALEKIT_CLIENT_SECRET")
11
)
12
13
# Resource configuration
14
# Get these values from Scalekit dashboard > MCP servers > Your server
15
# For FastMCP: Use base URL with trailing slash (e.g., https://mcp.example.com/)
16
RESOURCE_ID = "res_123456789" # Resource ID (res_...) from Dashboard > MCP servers > Your server. Used as the token audience and in the issuer.
17
METADATA_ENDPOINT = "https://your-mcp-server.com/.well-known/oauth-protected-resource"
18
19
# WWW-Authenticate header for unauthorized responses
20
# This helps clients understand how to authenticate properly
21
WWW_HEADER = {
22
"WWW-Authenticate": f'Bearer realm="OAuth", resource_metadata="{METADATA_ENDPOINT}"'
23
}
```
Extract the Bearer token from incoming MCP client requests. MCP clients send tokens in the `Authorization: Bearer ` header format. * Node.js
```javascript
// 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
```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’s issuer and audience to ensure it was issued for your specific MCP server. The issuer (`iss`) tells you who minted the token. For your MCP server, it is your environment URL followed by `/resources/` and your resource ID. Set `RESOURCE_ID` to the resource ID (`res_...`) shown for your MCP server in the Scalekit dashboard. Tokens for your MCP server also include it as an audience. * Node.js Validate token
```javascript
// Security: Validate token against configured resource audience
// This ensures the token was issued for your specific MCP server
const ENV_URL = process.env.SCALEKIT_ENVIRONMENT_URL;
await scalekit.validateToken(token, {
// Issuer is your environment URL followed by this MCP server's resource path
issuer: `${ENV_URL}/resources/${RESOURCE_ID}`,
audience: [RESOURCE_ID]
});
```
* Python Validate token
```python
1
ENV_URL = os.getenv("SCALEKIT_ENVIRONMENT_URL")
2
# Issuer is your environment URL followed by this MCP server's resource path
3
ISSUER = f"{ENV_URL}/resources/{RESOURCE_ID}"
4
5
# Method 1: validate_access_token - Returns boolean (True/False)
6
# Use this method when you only need to verify token validity without detailed error information.
7
# This approach is suitable for simple authorization checks where you don't need token claims.
8
def validate_token_with_issuer_audience(token: str) -> bool:
9
"""
10
Validates a token and returns True if valid, False otherwise.
11
12
:param token: The token to validate
13
:return: True if token is valid, False otherwise
14
"""
15
options = TokenValidationOptions(
16
issuer=ISSUER,
17
audience=[RESOURCE_ID]
18
)
19
20
try:
21
is_valid = scalekit_client.validate_access_token(token, options=options)
22
return is_valid
23
except Exception as ex:
24
print(f"Token validation failed: {ex}")
25
return False
26
27
# Method 2: validate_token - Returns token claims/payload
28
# Use this method when you need access to token claims (user info, scopes, etc.) or detailed error information.
29
# This approach is suitable for authorization that requires specific user context or scope validation.
30
def validate_token_and_get_claims(token: str) -> dict:
31
"""
32
Validates a token with specific audience and raises exception on failure.
33
34
:param token: The token to validate
35
:raises: ScalekitValidateTokenFailureException if validation fails
36
"""
37
options = TokenValidationOptions(
38
issuer=ISSUER,
39
audience=[RESOURCE_ID],
40
required_scopes=["todo:read", "todo:write"] # Optional: validate specific scopes for finer access control
41
)
42
43
scalekit_client.validate_token(token, options=options)
```
* Go middleware/auth.go
```go
1
// Security: validate the token's issuer and audience — confirms it was issued by
2
// your Scalekit environment for your specific MCP server.
3
envURL := os.Getenv("SCALEKIT_ENVIRONMENT_URL")
4
5
ok, err := scalekitClient.ValidateTokenWithOptions(ctx, token, &scalekit.ValidateTokenOptions{
6
// Issuer is your environment URL followed by this MCP server's resource path
7
Issuer: envURL + "/resources/" + RESOURCE_ID,
8
Audience: []string{RESOURCE_ID},
9
})
10
if err != nil || !ok {
11
// Reject: return 401 with the WWW-Authenticate header and stop processing.
12
w.Header().Set("WWW-Authenticate", wwwAuthenticateHeader)
13
http.Error(w, "invalid token", http.StatusUnauthorized)
14
return
15
}
16
// Token is valid — continue handling the request.
17
18
// Prefer validating scopes per tool-call rather than in this global check, so each
19
// tool enforces only the scope it needs.
```
* Java middleware/AuthMiddleware.java
```java
1
// Security: validate the token's issuer and audience — confirms it was issued by
2
// your Scalekit environment for your specific MCP server.
3
String envUrl = System.getenv("SCALEKIT_ENVIRONMENT_URL");
4
5
boolean isValid = scalekitClient.authentication().validateAccessToken(
6
token,
7
TokenValidationOptions.builder()
8
// Issuer is your environment URL followed by this MCP server's resource path
9
.issuer(envUrl + "/resources/" + RESOURCE_ID)
10
.audience(List.of(RESOURCE_ID))
11
.build()
12
);
13
if (!isValid) {
14
// Reject: return 401 with the WWW-Authenticate header and stop processing.
15
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
16
response.setHeader("WWW-Authenticate", wwwAuthenticateHeader);
17
return;
18
}
19
// Token is valid — continue handling the request.
20
21
// Prefer enforcing scopes per tool-call rather than in this global check: read the
22
// token's "scope" claim via validateAccessTokenAndGetClaims(token, options) inside
23
// each tool and verify it contains the scope that tool needs.
```
#### Complete middleware implementation [Section titled “Complete middleware implementation”](#complete-middleware-implementation) Combine token extraction and validation into a complete authentication middleware that protects all your MCP endpoints. * Node.js
```javascript
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 = 'res_123456789'; // Resource ID (res_...) from Dashboard > MCP servers > Your server. Used as the token audience and in the issuer.
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
const envUrl = process.env.SCALEKIT_ENVIRONMENT_URL;
await scalekit.validateToken(token, {
issuer: `${envUrl}/resources/${RESOURCE_ID}`,
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
```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 = "res_123456789" # Resource ID (res_...) from Dashboard > MCP servers > Your server. Used as the token audience and in the issuer.
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:
env_url = os.getenv("SCALEKIT_ENVIRONMENT_URL")
options = TokenValidationOptions(
issuer=f"{env_url}/resources/{RESOURCE_ID}",
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 [Section titled “Implement scope-based tool authorization ”](#implement-scope-based-tool-authorization-) 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
```diff
1
// Security: Validate token has required scope for this specific tool execution
2
// Use case: Ensure users only have access to authorized MCP tools
3
try {
4
await scalekit.validateToken(
5
token, {
6
audience: [RESOURCE_ID],
7
requiredScopes: [scope]
8
}
9
);
10
} catch(error) {
11
// Return OAuth 2.0 compliant error for insufficient scope
12
return res.status(403).json({
13
error: 'insufficient_scope',
14
error_description: `Required scope: ${scope}`,
15
scope: scope
16
});
17
}
```
* Python
```diff
1
# Security: Validate token has required scope for this specific tool execution
2
# Use case: Ensure users only have access to authorized MCP tools
3
try:
4
scalekit_client.validate_access_token(
5
token,
6
options=TokenValidationOptions(
7
audience=[RESOURCE_ID],
8
+required_scopes=[scope]
9
)
10
)
11
except ScalekitValidateTokenFailureException as ex:
12
# Return OAuth 2.0 compliant error for insufficient scope
13
return {
14
"error": "insufficient_scope",
15
"error_description": f"Required scope: {scope}",
16
"scope": scope
17
}
```
6. ## Enable additional authentication methods [Section titled “Enable additional authentication methods”](#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](/mcp/auth-methods/enterprise/)** 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 **[Social logins](/mcp/auth-methods/social/)** 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](/mcp/auth-methods/custom-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](https://github.com/scalekit-inc/mcp-auth-demos) with authentication already configured to see the complete integration in action. 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.
---
# DOCUMENT BOUNDARY
---
# MCP Auth code samples
> MCP Auth authentication examples and patterns
### [Add Auth to Node.js MCP Servers](https://github.com/scalekit-inc/mcp-auth-demos/tree/main/greeting-mcp-node) [Add Scalekit auth to a Node.js MCP server with minimal setup. Includes a working example with user greeting.](https://github.com/scalekit-inc/mcp-auth-demos/tree/main/greeting-mcp-node) ### [Add Auth to Python MCP Servers](https://github.com/scalekit-inc/mcp-auth-demos/tree/main/greeting-mcp-python) [Add Scalekit auth to a Python MCP server in minutes. Includes a working example with user greeting.](https://github.com/scalekit-inc/mcp-auth-demos/tree/main/greeting-mcp-python) ### [Secure FastMCP Apps with Auth](https://github.com/scalekit-inc/mcp-auth-demos/tree/main/todo-fastmcp) [Build a secure FastMCP app with Scalekit. Features a complete todo list with protected endpoints and session management.](https://github.com/scalekit-inc/mcp-auth-demos/tree/main/todo-fastmcp)
---
# DOCUMENT BOUNDARY
---
# Publish your MCP connector to Claude & ChatGPT
> Give MCP connector directory reviewers a test user and static code so they can authenticate and test your server end to end.
To list your MCP connector in the [Claude connector directory](https://claude.com/docs/connectors/building/submission) or the [ChatGPT app directory](https://developers.openai.com/apps-sdk/deploy/submission#review-and-approval-faqs), a reviewer must sign in to your server and run every tool end to end. Both submission forms have a testing-access step that expects every credential and step needed to reach a fully-populated account. Scalekit’s [Test Users](/authenticate/run-e2e-tests/) feature makes this possible without handing over a real inbox: allowlist a reviewer email and set a **static 6-digit code**, and the reviewer signs in through Scalekit’s hosted login using that code. This page shows how to prepare the credential and write the instructions to paste into the submission form. Works only with Scalekit-managed auth Test Users works only when **Scalekit manages your app’s login, sessions, and user management** (Full Stack Auth / SaaSKit), because it intercepts Scalekit’s own Magic Link/OTP delivery. It does **not** work when your MCP server runs in [Bring Your Own Auth](/mcp/auth-methods/custom-auth/) mode. In that mode Scalekit federates to your own identity provider and never owns the login screen or the OTP, so there is no static code to hand a reviewer. For Bring Your Own Auth, create a reviewer account directly in your identity provider and share those credentials instead. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * An MCP connector already protected with Scalekit MCP Auth using Scalekit-managed auth. See the [MCP Auth quickstart](/authenticate/mcp/quickstart/). * The **Magic Link & OTP** auth method enabled, with delivery set to `Verification Code` or `Magic Link + Verification Code`. `Magic Link`-only delivery is not supported. See the [Test Users prerequisite](/authenticate/run-e2e-tests/#prerequisites). ## How reviewer sign-in works [Section titled “How reviewer sign-in works”](#how-reviewer-sign-in-works) The reviewer follows the same OAuth 2.1 flow as any [human interacting with your MCP server](/authenticate/mcp/overview/#the-authorization-flow-in-practice): 1. The MCP client (MCP Inspector or Claude as a custom connector) calls your protected server and receives a `401` pointing to Scalekit. 2. The client redirects the reviewer to Scalekit’s hosted login. 3. The reviewer enters the **test email** and the **static code** you configured — no inbox required. 4. The reviewer approves the consent screen, Scalekit issues an access token, and the client runs your tools. ## Prepare the reviewer credential [Section titled “Prepare the reviewer credential”](#prepare-the-reviewer-credential) 1. ## Enable Test Users and add a reviewer email [Section titled “Enable Test Users and add a reviewer email”](#enable-test-users-and-add-a-reviewer-email) In **Dashboard > Environment settings > Test users**, toggle **Enable test users** and add a reviewer address. The email must contain `+sktest` in the local part — for example `reviewer+sktest@yourapp.com`. Set the **Static confirmation code** (the default is `424242`). For the full field-by-field reference, see [Configure test users](/authenticate/run-e2e-tests/#configure-test-users). 2. ## Create the reviewer inside a fully-populated organization [Section titled “Create the reviewer inside a fully-populated organization”](#create-the-reviewer-inside-a-fully-populated-organization) Reviewers expect your tools to return real data, so add the reviewer user to an organization that already has representative content. Create the user with `sendInvitationEmail: false` so no email goes out, then confirm the same email is on the Test Users allowlist. * Node.js Create the reviewer user
```ts
1
import { ScalekitClient } from '@scalekit-sdk/node'
2
3
const scalekit = new ScalekitClient(
4
process.env.SCALEKIT_ENVIRONMENT_URL!,
5
process.env.SCALEKIT_CLIENT_ID!,
6
process.env.SCALEKIT_CLIENT_SECRET!
7
)
8
9
try {
10
// Add the reviewer to a populated org so tools return real data during review.
11
const { user } = await scalekit.user.createUserAndMembership(orgId, {
12
email: 'reviewer+sktest@yourapp.com',
13
sendInvitationEmail: false,
14
})
15
} catch (error) {
16
console.error('Failed to create reviewer user:', error)
17
}
```
* Python Create the reviewer user
```python
1
import os
2
from scalekit import ScalekitClient
3
from scalekit.v1.users.users_pb2 import CreateUser
4
5
scalekit_client = ScalekitClient(
6
env_url=os.environ["SCALEKIT_ENVIRONMENT_URL"],
7
client_id=os.environ["SCALEKIT_CLIENT_ID"],
8
client_secret=os.environ["SCALEKIT_CLIENT_SECRET"],
9
)
10
11
try:
12
# Add the reviewer to a populated org so tools return real data during review.
13
user_response = scalekit_client.users.create_user_and_membership(
14
org_id,
15
CreateUser(email="reviewer+sktest@yourapp.com"),
16
send_invitation_email=False,
17
)
18
except Exception as error:
19
print(f"Failed to create reviewer user: {error}")
```
* Go Create the reviewer user
```go
1
import usersv1 "github.com/scalekit-inc/scalekit-sdk-go/v2/pkg/grpc/scalekit/v1/users"
2
3
scalekitClient := scalekit.NewScalekitClient(
4
os.Getenv("SCALEKIT_ENVIRONMENT_URL"),
5
os.Getenv("SCALEKIT_CLIENT_ID"),
6
os.Getenv("SCALEKIT_CLIENT_SECRET"),
7
)
8
9
// Add the reviewer to a populated org so tools return real data during review.
10
userResp, err := scalekitClient.User().CreateUserAndMembership(ctx, orgID,
11
&usersv1.CreateUser{Email: "reviewer+sktest@yourapp.com"},
12
false,
13
)
14
if err != nil {
15
log.Fatalf("failed to create reviewer user: %v", err)
16
}
```
* Java Create the reviewer user
```java
1
import com.scalekit.grpc.scalekit.v1.users.*;
2
3
ScalekitClient scalekitClient = new ScalekitClient(
4
System.getenv("SCALEKIT_ENVIRONMENT_URL"),
5
System.getenv("SCALEKIT_CLIENT_ID"),
6
System.getenv("SCALEKIT_CLIENT_SECRET")
7
);
8
9
try {
10
// Add the reviewer to a populated org so tools return real data during review.
11
CreateUserAndMembershipRequest request = CreateUserAndMembershipRequest.newBuilder()
12
.setUser(CreateUser.newBuilder().setEmail("reviewer+sktest@yourapp.com").build())
13
.setSendInvitationEmail(false)
14
.build();
15
16
CreateUserAndMembershipResponse userResp = scalekitClient.users()
17
.createUserAndMembership(orgId, request);
18
} catch (Exception error) {
19
System.err.println("Failed to create reviewer user: " + error.getMessage());
20
}
```
## Verify [Section titled “Verify”](#verify) Connect to your server the same way the reviewer will — via [MCP Inspector](https://github.com/modelcontextprotocol/inspector) or as a custom connector in Claude — and sign in with the reviewer email and static code. Verification succeeds when: * Sign-in completes with the static code and no real verification email is sent. * Every tool runs successfully and returns representative data from the populated organization. Fix any gaps before you submit to a directory. ## Write the test setup instructions [Section titled “Write the test setup instructions”](#write-the-test-setup-instructions) Paste instructions into the submission form’s testing-access field — the **Test setup instructions** box on Claude’s **Test & launch** step, or the equivalent testing-instructions field in the ChatGPT app submission. Give the reviewer everything needed to authenticate autonomously: Test setup instructions (paste-ready)
```text
Connector URL: https://mcp.yourapp.com/mcp
Authentication: OAuth 2.0 (hosted login). When prompted to connect, use the
test account below — no email inbox is required.
Email: reviewer+sktest@yourapp.com
Verification code: 424242
Steps:
1. Add the connector and start the OAuth sign-in.
2. On the login screen, enter the email above and continue.
3. At the verification-code prompt, enter 424242 and continue.
4. Approve the consent screen.
5. The account belongs to a fully-populated organization, so every tool
returns representative data.
```
Replace the URL, email, and code with your own values. Keep the code identical to the **Static confirmation code** configured in the dashboard. ## Next steps [Section titled “Next steps”](#next-steps) Once your connector is approved, remove the reviewer email from the allowlist or rotate the static code — see [Configure test users](/authenticate/run-e2e-tests/#configure-test-users) for how to manage the allowlist. ## Common scenarios [Section titled “Common scenarios”](#common-scenarios)
---
# DOCUMENT BOUNDARY
---
# Express.js quickstart
> Build a production-ready Express.js MCP server with TypeScript, custom middleware for OAuth token validation, and Scalekit authentication.
This guide shows you how to build a production-ready Express.js MCP server with TypeScript and Scalekit’s OAuth authentication. You’ll implement custom middleware for token validation, expose OAuth resource metadata for client discovery, and create MCP tools that enforce authorization using the MCP SDK. Use this quickstart when you’re building Node.js-based MCP servers and want fine-grained control over request handling. The Express integration gives you flexibility to add custom routes, middleware chains, integrate with existing Express applications, and handle complex authorization requirements. The full code is available on [GitHub](https://github.com/scalekit-inc/mcp-auth-demos/tree/main/greeting-mcp-node). **Prerequisites** * A [Scalekit account](https://app.scalekit.com) with permission to manage MCP servers * **Node.js 20+** installed locally * Familiarity with Express.js, TypeScript, and OAuth token validation * Basic understanding of MCP server architecture 1. ## Register your MCP server in Scalekit [Section titled “Register your MCP server in Scalekit”](#register-your-mcp-server-in-scalekit) Create a protected resource entry so Scalekit can issue tokens that your custom Express middleware validates. 1. Navigate to **[Dashboard](https://app.scalekit.com) > MCP Servers > Add MCP Server**. 2. Enter a descriptive name (for example, `Greeting MCP`). 3. Set **Server URL** to `http://localhost:3002/` (keep the trailing slash). 4. Click **Save** to create the server.  When you save, Scalekit displays the OAuth-protected resource metadata. Copy this JSON—you’ll use it in your `.env` file.  2. ## Create your project directory [Section titled “Create your project directory”](#create-your-project-directory) Set up a clean directory structure for your TypeScript Express project. Terminal
```bash
mkdir express-mcp-node
cd express-mcp-node
```
3. ## Add package dependencies [Section titled “Add package dependencies”](#add-package-dependencies) Create a `package.json` with scripts and all required dependencies for Express, TypeScript, and the MCP SDK. Terminal
```bash
1
cat <<'EOF' > package.json
2
{
3
"name": "express-mcp-node",
4
"version": "1.0.0",
5
"type": "module",
6
"scripts": {
7
"dev": "tsx src/server.ts",
8
"build": "tsc",
9
"start": "node dist/server.js"
10
},
11
"dependencies": {
12
"@modelcontextprotocol/sdk": "^1.13.0",
13
"@scalekit-sdk/node": "^2.0.1",
14
"cors": "^2.8.5",
15
"dotenv": "^16.4.5",
16
"express": "^5.1.0",
17
"zod": "^3.25.57"
18
},
19
"devDependencies": {
20
"@types/cors": "^2.8.19",
21
"@types/express": "^4.17.21",
22
"@types/node": "^20.11.19",
23
"tsx": "^4.7.0",
24
"typescript": "^5.4.5"
25
}
26
}
27
EOF
```
4. ## Configure TypeScript [Section titled “Configure TypeScript”](#configure-typescript) Add a TypeScript configuration file optimized for ES2022 modules and strict type checking. Terminal
```bash
1
cat <<'EOF' > tsconfig.json
2
{
3
"compilerOptions": {
4
"target": "ES2022",
5
"module": "ES2022",
6
"moduleResolution": "node",
7
"esModuleInterop": true,
8
"forceConsistentCasingInFileNames": true,
9
"strict": false,
10
"skipLibCheck": true,
11
"resolveJsonModule": true,
12
"outDir": "dist",
13
"rootDir": "src",
14
"types": ["node"]
15
},
16
"include": ["src/**/*"]
17
}
18
EOF
```
5. ## Install dependencies [Section titled “Install dependencies”](#install-dependencies) Install all packages declared in `package.json`. Terminal
```bash
npm install
```
6. ## Configure environment variables [Section titled “Configure environment variables”](#configure-environment-variables) Create a `.env` file with your Scalekit credentials and the protected resource metadata from step 1. Terminal
```bash
cat <<'EOF' > .env
PORT=3002
SK_ENV_URL=https://.scalekit.com
SK_CLIENT_ID=
SK_CLIENT_SECRET=
MCP_SERVER_ID=
PROTECTED_RESOURCE_METADATA=''
EXPECTED_AUDIENCE=http://localhost:3002/
EOF
open .env
```
| Variable | Description | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `PORT` | Local port for the Express server. Must match the Server URL registered in Scalekit (defaults to `3002`). | | `SK_ENV_URL` | Your Scalekit environment URL from **Dashboard > Settings > API Credentials** | | `SK_CLIENT_ID` | Client ID from **Dashboard > Settings > API Credentials**. Used with `SK_CLIENT_SECRET` to initialize the SDK. | | `SK_CLIENT_SECRET` | Client secret from **Dashboard > Settings > API Credentials**. Keep this secret and rotate regularly. | | `MCP_SERVER_ID` | The MCP server ID (`res_...`) from **Dashboard > MCP Servers**. Used to build the token issuer. | | `PROTECTED_RESOURCE_METADATA` | The complete OAuth resource metadata JSON from step 1. Clients use this to discover authorization requirements. | | `EXPECTED_AUDIENCE` | The audience value that tokens must include. Should match your server’s public URL (e.g., `http://localhost:3002/`). | Protect your credentials Never commit `.env` to version control. Add it to `.gitignore` immediately and use a secret manager in production (e.g., AWS Secrets Manager, HashiCorp Vault, or your deployment platform’s secrets service). 7. ## Implement the Express MCP server [Section titled “Implement the Express MCP server”](#implement-the-express-mcp-server) This server validates tokens whose issuer (`iss`) is `/resources/`. If you see the **Resource bound issuer** option on your MCP server in the Scalekit dashboard, your workspace was created before October 21, 2026. Until you enable that option, your tokens carry your environment URL as the issuer, and this server rejects them with a `401`. Follow [Migrate to the new MCP spec](/authenticate/mcp/migrate-to-2026-07-28-mcp-spec/) first. Create `src/server.ts` with the complete server implementation. This includes the Scalekit client initialization, authentication middleware for token validation, CORS configuration, and the greeting MCP tool. src/server.ts
```typescript
1
import 'dotenv/config';
2
import cors from 'cors';
3
import express, { NextFunction, Request, Response } from 'express';
4
import { z } from 'zod';
5
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
6
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
7
import { Scalekit } from '@scalekit-sdk/node';
8
9
// Load environment variables
10
const PORT = Number(process.env.PORT ?? 3002);
11
const SK_ENV_URL = process.env.SK_ENV_URL ?? '';
12
const SK_CLIENT_ID = process.env.SK_CLIENT_ID ?? '';
13
const SK_CLIENT_SECRET = process.env.SK_CLIENT_SECRET ?? '';
14
const MCP_SERVER_ID = process.env.MCP_SERVER_ID ?? '';
15
const EXPECTED_AUDIENCE = process.env.EXPECTED_AUDIENCE ?? '';
16
const PROTECTED_RESOURCE_METADATA = process.env.PROTECTED_RESOURCE_METADATA ?? '';
17
18
// Use case: Configure OAuth resource metadata URL for MCP clients
19
// This allows MCP clients to discover authorization requirements via WWW-Authenticate header
20
// Security: The WWW-Authenticate header signals to clients where to obtain tokens
21
const RESOURCE_METADATA_URL = `http://localhost:${PORT}/.well-known/oauth-protected-resource`;
22
23
// WWW-Authenticate header for 401 responses
24
const WWW_HEADER_KEY = 'WWW-Authenticate';
25
const WWW_HEADER_VALUE = `Bearer realm="OAuth", resource_metadata="${RESOURCE_METADATA_URL}"`;
26
27
// Initialize Scalekit client for token validation
28
// Security: Use SDK to validate JWT signatures and claims
29
// This prevents accepting forged or tampered tokens
30
const scalekit = new Scalekit(SK_ENV_URL, SK_CLIENT_ID, SK_CLIENT_SECRET);
31
32
// Initialize MCP server with greeting tool
33
// Context: The McpServer handles MCP protocol details while Express handles HTTP routing
34
const server = new McpServer({ name: 'Greeting MCP', version: '1.0.0' });
35
36
// Use case: Simple greeting tool demonstrating OAuth-protected MCP operations
37
// Context: This tool is protected by the authentication middleware applied to all routes
38
server.tool(
39
'greet_user',
40
'Greets the user with a personalized message.',
41
{
42
name: z.string().min(1, 'Name is required'),
43
},
44
async ({ name }: { name: string }) => ({
45
content: [
46
{
47
type: 'text',
48
text: `Hi ${name}, welcome to Scalekit!`
49
}
50
]
51
})
52
);
53
54
// Initialize Express application
55
const app = express();
56
57
// Enable CORS for cross-origin MCP clients
58
// Use case: Allow MCP clients from different origins to connect
59
app.use(cors({ origin: true, credentials: false }));
60
61
// Parse JSON request bodies
62
// Context: MCP protocol uses JSON-RPC format
63
app.use(express.json());
64
65
// Use case: Expose OAuth resource metadata for MCP client discovery
66
// This endpoint allows clients to discover authorization requirements and server capabilities
67
// Context: MCP clients use this metadata to initiate the OAuth flow
68
app.get('/.well-known/oauth-protected-resource', (_req: Request, res: Response) => {
69
if (!PROTECTED_RESOURCE_METADATA) {
70
res.status(500).json({ error: 'PROTECTED_RESOURCE_METADATA config missing' });
71
return;
72
}
73
74
const metadata = JSON.parse(PROTECTED_RESOURCE_METADATA);
75
res.type('application/json').send(JSON.stringify(metadata, null, 2));
76
});
77
78
// Use case: Health check endpoint for monitoring and load balancers
79
// Context: Keep this separate from protected endpoints for deployment health checks
80
app.get('/health', (_req: Request, res: Response) => {
81
res.json({ status: 'healthy' });
82
});
83
84
// Security: Validate Bearer tokens on all protected endpoints
85
// Public endpoints (health, metadata) are exempt from authentication
86
// This prevents unauthorized access to MCP tools and operations
87
app.use(async (req: Request, res: Response, next: NextFunction) => {
88
// Allow public endpoints without authentication
89
// Use case: Health checks for monitoring; metadata for client discovery
90
if (req.path === '/.well-known/oauth-protected-resource' || req.path === '/health') {
91
next();
92
return;
93
}
94
95
// Extract Bearer token from Authorization header
96
// Use case: OAuth 2.1 Bearer token format (RFC 6750)
97
// Security: Reject requests without valid Bearer token prefix
98
const header = req.headers.authorization;
99
const token = header?.startsWith('Bearer ')
100
? header.slice('Bearer '.length).trim()
101
: undefined;
102
103
if (!token) {
104
res.status(401)
105
.set(WWW_HEADER_KEY, WWW_HEADER_VALUE)
106
.json({ error: 'Missing Bearer token' });
107
return;
108
}
109
110
try {
111
// Validate token using Scalekit SDK
112
// Security: Verifies signature, expiration, issuer, and audience claims
113
// Context: This critical step prevents accepting tokens from other issuers
114
await scalekit.validateToken(token, { issuer: `${SK_ENV_URL}/resources/${MCP_SERVER_ID}`, audience: [EXPECTED_AUDIENCE] });
115
next();
116
} catch (error) {
117
res.status(401)
118
.set(WWW_HEADER_KEY, WWW_HEADER_VALUE)
119
.json({ error: 'Token validation failed' });
120
}
121
});
122
123
// Handle MCP protocol requests at root path
124
// Use case: Process authenticated MCP tool requests using StreamableHTTPServerTransport
125
// Context: The transport layer handles MCP JSON-RPC communication
126
app.post('/', async (req: Request, res: Response) => {
127
const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
128
await server.connect(transport);
129
130
try {
131
await transport.handleRequest(req, res, req.body);
132
} catch (error) {
133
res.status(500).json({ error: 'MCP transport error' });
134
}
135
});
136
137
// Start the Express server
138
app.listen(PORT, () => {
139
console.log(`MCP server running on http://localhost:${PORT}`);
140
});
```
8. ## Start the Express server [Section titled “Start the Express server”](#start-the-express-server) Start the Express server in development mode with auto-reload enabled. The server will listen on `http://localhost:3002/` and display logs indicating Express is ready to receive authenticated MCP requests. Terminal
```bash
npm run dev
```
The server starts on `http://localhost:3002/` and logs indicate Express is ready. The MCP endpoint at `/` accepts authenticated POST requests, and the metadata endpoint is accessible at `/.well-known/oauth-protected-resource`. 9. ## Connect with MCP Inspector [Section titled “Connect with MCP Inspector”](#connect-with-mcp-inspector) Test your server end-to-end using the MCP Inspector to verify the OAuth flow works correctly. This allows you to see the authentication handshake and test calling your MCP tools with validated tokens. Terminal
```bash
npx @modelcontextprotocol/inspector@latest
```
In the Inspector UI: 1. Enter your MCP Server URL: `http://localhost:3002/` 2. Click **Connect** to initiate the OAuth flow 3. Authenticate with Scalekit when prompted 4. Run the `greet_user` tool with any name  You now have a working Express.js MCP server with Scalekit-protected OAuth authentication. Extend this implementation by adding more MCP tools using `server.tool()` with Zod schema validation, implementing scope-based authorization using custom middleware, integrating with your existing Express application, or adding features like rate limiting and request logging using Express’s middleware ecosystem.
---
# DOCUMENT BOUNDARY
---
# FastAPI + FastMCP quickstart
> Build a production-ready MCP server with FastAPI custom middleware for OAuth token validation and Scalekit authentication.
This guide shows you how to build a production-ready FastAPI + FastMCP server with Scalekit’s OAuth authentication. You’ll implement custom middleware for token validation, expose OAuth resource metadata for client discovery, and create MCP tools that enforce authorization. Use this quickstart when you need more control over your server’s behavior than FastMCP’s built-in provider offers. The FastAPI integration gives you flexibility to add custom middleware, implement additional endpoints, integrate with existing FastAPI applications, and handle complex authorization requirements. The full code is available on [GitHub](https://github.com/scalekit-inc/mcp-auth-demos/tree/main/greeting-mcp-python). **Prerequisites** * A [Scalekit account](https://app.scalekit.com) with permission to manage MCP servers * **Python 3.11+** installed locally * Familiarity with FastAPI and OAuth token validation * Basic understanding of MCP server architecture 1. ## Register your MCP server in Scalekit [Section titled “Register your MCP server in Scalekit”](#register-your-mcp-server-in-scalekit) Create a protected resource entry so Scalekit can issue tokens that your custom FastAPI middleware validates. 1. Navigate to **[Dashboard](https://app.scalekit.com) > MCP Servers > Add MCP Server**. 2. Enter a descriptive name (for example, `Greeting MCP`). 3. Set **Server URL** to `http://localhost:3002/` (keep the trailing slash). 4. Click **Save** to create the server.  When you save, Scalekit displays the OAuth-protected resource metadata. Copy this JSON—you’ll use it in your `.env` file.  2. ## Create your project directory [Section titled “Create your project directory”](#create-your-project-directory) Set up a clean directory structure with a Python virtual environment to isolate FastAPI and FastMCP dependencies. Terminal
```bash
mkdir fastapi-mcp-python
cd fastapi-mcp-python
python3 -m venv .venv
source .venv/bin/activate
```
3. ## Add dependencies [Section titled “Add dependencies”](#add-dependencies) Create a `requirements.txt` file with all required packages and install them. Terminal
```bash
cat <<'EOF' > requirements.txt
mcp>=1.0.0
fastapi>=0.104.0
fastmcp>=0.8.0
uvicorn>=0.24.0
pydantic>=2.5.0
python-dotenv>=1.0.0
httpx>=0.25.0
python-jose[cryptography]>=3.3.0
cryptography>=41.0.0
scalekit-sdk-python>=2.4.0
starlette>=0.27.0
EOF
pip install -r requirements.txt
```
4. ## Configure environment variables [Section titled “Configure environment variables”](#configure-environment-variables) Create a `.env` file with your Scalekit credentials and the protected resource metadata from step 1. Terminal
```bash
cat <<'EOF' > .env
PORT=3002
SK_ENV_URL=https://.scalekit.com
SK_CLIENT_ID=
SK_CLIENT_SECRET=
MCP_SERVER_ID=
PROTECTED_RESOURCE_METADATA=''
EXPECTED_AUDIENCE=http://localhost:3002/
EOF
open .env
```
| Variable | Description | | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `PORT` | Local port for the FastAPI server. Must match the Server URL registered in Scalekit (defaults to `3002`). | | `SK_ENV_URL` | Your Scalekit environment URL from **Dashboard > Settings > API Credentials** | | `SK_CLIENT_ID` | Client ID from **Dashboard > Settings > API Credentials**. Used with `SK_CLIENT_SECRET` to initialize the SDK. | | `SK_CLIENT_SECRET` | Client secret from **Dashboard > Settings > API Credentials**. Keep this secret and rotate regularly. | | `MCP_SERVER_ID` | The MCP server ID (`res_...`) from **Dashboard > MCP Servers**. Used to build the token issuer. | | `PROTECTED_RESOURCE_METADATA` | The complete OAuth resource metadata JSON from step 1. Clients use this to discover authorization requirements. | | `EXPECTED_AUDIENCE` | The audience value that tokens must include. Should match your server’s public URL (e.g., `http://localhost:3002/`). | Protect your credentials Never commit `.env` to version control. Add it to `.gitignore` immediately and use a secret manager in production (e.g., AWS Secrets Manager, HashiCorp Vault, or your deployment platform’s secrets service). 5. ## Implement the FastAPI + FastMCP server [Section titled “Implement the FastAPI + FastMCP server”](#implement-the-fastapi--fastmcp-server) This server validates tokens whose issuer (`iss`) is `/resources/`. If you see the **Resource bound issuer** option on your MCP server in the Scalekit dashboard, your workspace was created before October 21, 2026. Until you enable that option, your tokens carry your environment URL as the issuer, and this server rejects them with a `401`. Follow [Migrate to the new MCP spec](/authenticate/mcp/migrate-to-2026-07-28-mcp-spec/) first. Create `main.py` with the complete server implementation. This includes the Scalekit client initialization, authentication middleware for token validation, CORS configuration, and the greeting MCP tool. main.py
```python
1
import json
2
import os
3
from fastapi import FastAPI, Request, Response
4
from fastmcp import FastMCP, Context
5
from scalekit import ScalekitClient
6
from scalekit.common.scalekit import TokenValidationOptions
7
from starlette.middleware.cors import CORSMiddleware
8
from dotenv import load_dotenv
9
10
load_dotenv()
11
12
# Load environment variables
13
PORT = int(os.getenv("PORT", "3002"))
14
SK_ENV_URL = os.getenv("SK_ENV_URL", "")
15
SK_CLIENT_ID = os.getenv("SK_CLIENT_ID", "")
16
SK_CLIENT_SECRET = os.getenv("SK_CLIENT_SECRET", "")
17
MCP_SERVER_ID = os.getenv("MCP_SERVER_ID", "")
18
EXPECTED_AUDIENCE = os.getenv("EXPECTED_AUDIENCE", "")
19
PROTECTED_RESOURCE_METADATA = os.getenv("PROTECTED_RESOURCE_METADATA", "")
20
21
# Use case: Configure OAuth resource metadata URL for MCP clients
22
# This allows MCP clients to discover authorization requirements via WWW-Authenticate header
23
# Security: The WWW-Authenticate header signals to clients where to obtain tokens
24
RESOURCE_METADATA_URL = f"http://localhost:{PORT}/.well-known/oauth-protected-resource"
25
WWW_HEADER = {
26
"WWW-Authenticate": f'Bearer realm="OAuth", resource_metadata="{RESOURCE_METADATA_URL}"'
27
}
28
29
# Initialize Scalekit client for token validation
30
# Security: Use SDK to validate JWT signatures and claims
31
# This prevents accepting forged or tampered tokens
32
scalekit_client = ScalekitClient(
33
env_url=SK_ENV_URL,
34
client_id=SK_CLIENT_ID,
35
client_secret=SK_CLIENT_SECRET,
36
)
37
38
# Initialize FastMCP with stateless HTTP transport
39
# HTTP transport allows MCP clients to connect via standard OAuth flows
40
mcp = FastMCP("Greeting MCP", stateless_http=True)
41
42
43
@mcp.tool(
44
name="greet_user",
45
description="Greets the user with a personalized message."
46
)
47
async def greet_user(name: str, ctx: Context | None = None) -> dict:
48
"""
49
Use case: Simple greeting tool demonstrating OAuth-protected MCP operations
50
Context: This tool is protected by the authentication middleware
51
"""
52
return {
53
"content": [
54
{
55
"type": "text",
56
"text": f"Hi {name}, welcome to Scalekit!"
57
}
58
]
59
}
60
61
62
# Mount FastMCP as a FastAPI application
63
# Context: This allows us to layer FastAPI middleware on top of FastMCP
64
mcp_app = mcp.http_app(path="/")
65
app = FastAPI(lifespan=mcp_app.lifespan)
66
67
# Enable CORS for cross-origin MCP clients
68
# Use case: Allow MCP clients from different origins to connect
69
app.add_middleware(
70
CORSMiddleware,
71
allow_origins=["*"],
72
allow_credentials=True,
73
allow_methods=["GET", "POST", "OPTIONS"],
74
allow_headers=["*"]
75
)
76
77
78
@app.middleware("http")
79
async def auth_middleware(request: Request, call_next):
80
"""
81
Security: Validate Bearer tokens on all protected endpoints.
82
Public endpoints (health, metadata) are exempt from authentication.
83
This prevents unauthorized access to MCP tools and operations.
84
"""
85
# Allow public endpoints without authentication
86
# Use case: Health checks for monitoring; metadata for client discovery
87
if request.url.path in {"/health", "/.well-known/oauth-protected-resource"}:
88
return await call_next(request)
89
90
# Extract Bearer token from Authorization header
91
# Use case: OAuth 2.1 Bearer token format (RFC 6750)
92
# Security: Reject requests without valid Bearer token prefix
93
auth_header = request.headers.get("authorization")
94
if not auth_header or not auth_header.startswith("Bearer "):
95
return Response(
96
'{"error": "Missing Bearer token"}',
97
status_code=401,
98
headers=WWW_HEADER,
99
media_type="application/json"
100
)
101
102
token = auth_header.split("Bearer ", 1)[1].strip()
103
104
# Validate token using Scalekit SDK
105
# Security: Verifies signature, expiration, issuer, and audience claims
106
# Context: This critical step prevents accepting tokens from other issuers
107
options = TokenValidationOptions(
108
issuer=f"{SK_ENV_URL}/resources/{MCP_SERVER_ID}",
109
audience=[EXPECTED_AUDIENCE]
110
)
111
112
try:
113
is_valid = scalekit_client.validate_access_token(token, options=options)
114
if not is_valid:
115
raise ValueError("Invalid token")
116
except Exception:
117
return Response(
118
'{"error": "Token validation failed"}',
119
status_code=401,
120
headers=WWW_HEADER,
121
media_type="application/json"
122
)
123
124
# Token is valid, proceed with request
125
# This allows MCP clients to call tools with authenticated context
126
return await call_next(request)
127
128
129
@app.get("/.well-known/oauth-protected-resource")
130
async def oauth_metadata():
131
"""
132
Use case: Expose OAuth resource metadata for MCP client discovery
133
This endpoint allows clients to discover authorization requirements and server capabilities
134
Context: MCP clients use this metadata to initiate the OAuth flow
135
"""
136
if not PROTECTED_RESOURCE_METADATA:
137
return Response(
138
'{"error": "PROTECTED_RESOURCE_METADATA config missing"}',
139
status_code=500,
140
media_type="application/json"
141
)
142
143
metadata = json.loads(PROTECTED_RESOURCE_METADATA)
144
return Response(
145
json.dumps(metadata, indent=2),
146
media_type="application/json"
147
)
148
149
150
@app.get("/health")
151
async def health_check():
152
"""
153
Use case: Health check endpoint for monitoring and load balancers
154
Context: Keep this separate from protected endpoints for deployment health checks
155
"""
156
return {"status": "healthy"}
157
158
159
# Mount the FastMCP application at root path
160
app.mount("/", mcp_app)
161
162
163
if __name__ == "__main__":
164
import uvicorn
165
# Start server with auto-reload for development
166
# Production: Use 'uvicorn main:app --host 0.0.0.0 --port 3002 --workers 4' behind a reverse proxy
167
uvicorn.run(app, host="0.0.0.0", port=PORT)
```
6. ## Start the FastAPI server [Section titled “Start the FastAPI server”](#start-the-fastapi-server) Start the FastAPI server in development mode with auto-reload enabled. The server will listen on `http://localhost:3002/` and display logs indicating FastAPI is ready to receive authenticated MCP requests. Terminal
```bash
python main.py
```
The server starts on `http://localhost:3002/` and logs indicate FastAPI is ready. The MCP endpoint accepts authenticated requests, and the metadata endpoint is accessible at `/.well-known/oauth-protected-resource`. 7. ## Connect with MCP Inspector [Section titled “Connect with MCP Inspector”](#connect-with-mcp-inspector) Test your server end-to-end using the MCP Inspector to verify the OAuth flow works correctly. This allows you to see the authentication handshake and test calling your MCP tools with validated tokens. Terminal
```bash
npx @modelcontextprotocol/inspector@latest
```
In the Inspector UI: 1. Enter your MCP Server URL: `http://localhost:3002/` 2. Click **Connect** to initiate the OAuth flow 3. Authenticate with Scalekit when prompted 4. Run the `greet_user` tool with any name  You now have a working FastAPI + FastMCP server with Scalekit-protected OAuth authentication. Extend this implementation by adding more MCP tools with the `@mcp.tool` decorator, implementing scope-based authorization using custom middleware, integrating with your existing FastAPI application, or adding features like rate limiting and request logging using FastAPI’s middleware pipeline.
---
# DOCUMENT BOUNDARY
---
# FastMCP quickstart
> FastMCP todo server with OAuth scope validation and CRUD operations.
This guide shows you how to build a production-ready FastMCP server protected by Scalekit’s OAuth authentication. You’ll register your server as a protected resource, implement scope-based authorization for CRUD operations, and validate tokens on every request. Use this quickstart to experience a working reference implementation with a simple todo application. The todo app demonstrates how to enforce `todo:read` and `todo:write` scopes across multiple tools. After completing this guide, you can apply the same authentication pattern to secure your own FastMCP tools. The full code is available on [GitHub](https://github.com/scalekit-inc/mcp-demo/tree/main/todo-fastmcp). **Prerequisites** * A [Scalekit account](https://app.scalekit.com) with permission to manage MCP servers * **Python 3.11+** installed locally * Familiarity with OAuth scopes and basic terminal commands 1. ## Register your MCP server in Scalekit [Section titled “Register your MCP server in Scalekit”](#register-your-mcp-server-in-scalekit) Create a protected resource entry so Scalekit can issue scoped tokens that FastMCP validates on every request. 1. Navigate to **[Dashboard](https://app.scalekit.com) > MCP Servers > Add MCP Server**. 2. Enter a descriptive name (for example, `FastMCP Todo Server`). 3. Set **Server URL** to `http://localhost:3002/` (keep the trailing slash). This field is a required.\ For a server running at `http://localhost:3002/mcp`, register `http://localhost:3002/`. FastMCP appends `/mcp` automatically, so always provide the base URL with a trailing slash. 4. Create or link the scopes below, then click **Save**.  | Scope | Description | Required | | ------------ | -------------------------------------------- | -------- | | `todo:read` | Grants read access to todo tasks | Yes | | `todo:write` | Allows creating, updating, or deleting tasks | Yes | 2. ## Create your FastMCP todo server [Section titled “Create your FastMCP todo server”](#create-your-fastmcp-todo-server) Prepare a fresh directory and virtual environment to keep FastMCP dependencies isolated. Terminal
```bash
mkdir -p fastmcp-todo
cd fastmcp-todo
python3 -m venv venv
source venv/bin/activate
```
3. ## Add dependencies and configuration templates [Section titled “Add dependencies and configuration templates”](#add-dependencies-and-configuration-templates) Create the support files that FastMCP and Scalekit expect, then install the required libraries. Terminal
```bash
cat <<'EOF' > requirements.txt
fastmcp>=2.13.0.2
python-dotenv>=1.0.0
EOF
pip install -r requirements.txt
cat <<'EOF' > env.example
PORT=3002
SCALEKIT_ENVIRONMENT_URL=https://your-environment-url.scalekit.com
SCALEKIT_CLIENT_ID=your_client_id
SCALEKIT_RESOURCE_ID=mcp_server_id
MCP_URL=http://localhost:3002/
EOF
```
4. ## Implement the FastMCP todo server [Section titled “Implement the FastMCP todo server”](#implement-the-fastmcp-todo-server) Copy the following code into `server.py`. It registers the Scalekit provider, defines an in-memory todo store, and exposes CRUD tools guarded by OAuth scopes. server.py
```python
1
"""Scalekit-authenticated FastMCP server providing in-memory CRUD tools for todos.
2
3
This example demonstrates how to protect FastMCP tools with OAuth scopes.
4
Each tool validates the required scope before executing operations.
5
"""
6
7
import os
8
import uuid
9
from dataclasses import dataclass, asdict
10
from typing import Optional
11
12
from dotenv import load_dotenv
13
from fastmcp import FastMCP
14
from fastmcp.server.auth.providers.scalekit import ScalekitProvider
15
from fastmcp.server.dependencies import AccessToken, get_access_token
16
17
load_dotenv()
18
19
# Use case: Configure FastMCP server with OAuth protection
20
# Security: Scalekit provider validates every request's Bearer token
21
mcp = FastMCP(
22
"Todo Server",
23
stateless_http=True,
24
auth=ScalekitProvider(
25
environment_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
26
client_id=os.getenv("SCALEKIT_CLIENT_ID"),
27
resource_id=os.getenv("SCALEKIT_RESOURCE_ID"),
28
# FastMCP appends /mcp automatically; keep base URL with trailing slash only
29
mcp_url=os.getenv("MCP_URL"),
30
),
31
)
32
33
34
@dataclass
35
class TodoItem:
36
id: str
37
title: str
38
description: Optional[str]
39
completed: bool = False
40
41
def to_dict(self) -> dict:
42
return asdict(self)
43
44
45
# Use case: In-memory storage for demo purposes
46
# Production: Replace with your database or persistent storage
47
_TODO_STORE: dict[str, TodoItem] = {}
48
49
50
def _require_scope(scope: str) -> Optional[str]:
51
"""
52
Security: Validate that the current request's token includes the required scope.
53
This prevents unauthorized access to protected operations.
54
"""
55
token: AccessToken = get_access_token()
56
if scope not in token.scopes:
57
return f"Insufficient permissions: `{scope}` scope required."
58
return None
59
60
61
@mcp.tool
62
def create_todo(title: str, description: Optional[str] = None) -> dict:
63
"""
64
Use case: Create a new todo item for task tracking
65
Requires: todo:write scope
66
"""
67
error = _require_scope("todo:write")
68
if error:
69
return {"error": error}
70
71
todo = TodoItem(id=str(uuid.uuid4()), title=title, description=description)
72
_TODO_STORE[todo.id] = todo
73
return {"todo": todo.to_dict()}
74
75
76
@mcp.tool
77
def list_todos(completed: Optional[bool] = None) -> dict:
78
"""
79
Use case: Retrieve all todos, optionally filtered by completion status
80
Requires: todo:read scope
81
"""
82
error = _require_scope("todo:read")
83
if error:
84
return {"error": error}
85
86
todos = [
87
todo.to_dict()
88
for todo in _TODO_STORE.values()
89
if completed is None or todo.completed == completed
90
]
91
return {"todos": todos}
92
93
94
@mcp.tool
95
def get_todo(todo_id: str) -> dict:
96
"""
97
Use case: Retrieve a specific todo by ID
98
Requires: todo:read scope
99
"""
100
error = _require_scope("todo:read")
101
if error:
102
return {"error": error}
103
104
todo = _TODO_STORE.get(todo_id)
105
if todo is None:
106
return {"error": f"Todo `{todo_id}` not found."}
107
108
return {"todo": todo.to_dict()}
109
110
111
@mcp.tool
112
def update_todo(
113
todo_id: str,
114
title: Optional[str] = None,
115
description: Optional[str] = None,
116
completed: Optional[bool] = None,
117
) -> dict:
118
"""
119
Use case: Update existing todo properties or mark as complete
120
Requires: todo:write scope
121
"""
122
error = _require_scope("todo:write")
123
if error:
124
return {"error": error}
125
126
todo = _TODO_STORE.get(todo_id)
127
if todo is None:
128
return {"error": f"Todo `{todo_id}` not found."}
129
130
if title is not None:
131
todo.title = title
132
if description is not None:
133
todo.description = description
134
if completed is not None:
135
todo.completed = completed
136
137
return {"todo": todo.to_dict()}
138
139
140
@mcp.tool
141
def delete_todo(todo_id: str) -> dict:
142
"""
143
Use case: Remove a todo from the system
144
Requires: todo:write scope
145
"""
146
error = _require_scope("todo:write")
147
if error:
148
return {"error": error}
149
150
todo = _TODO_STORE.pop(todo_id, None)
151
if todo is None:
152
return {"error": f"Todo `{todo_id}` not found."}
153
154
return {"deleted": todo_id}
155
156
157
if __name__ == "__main__":
158
# Start HTTP transport server
159
mcp.run(transport="http", port=int(os.getenv("PORT", "3002")))
```
5. ## Provide runtime secrets [Section titled “Provide runtime secrets”](#provide-runtime-secrets) Copy the environment template and populate the values from your Scalekit dashboard. Terminal
```bash
cp env.example .env
open .env
```
| Variable | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `SCALEKIT_ENVIRONMENT_URL` | Your Scalekit environment URL, labeled **Environment URL** in **Dashboard > Settings > API Credentials** | | `SCALEKIT_CLIENT_ID` | Client ID from **Dashboard > Settings > API Credentials** | | `SCALEKIT_RESOURCE_ID` | The resource identifier assigned to your MCP server (starts with `res_`). Find it on your MCP server’s detail page in the dashboard. | | `MCP_URL` | The base public URL you registered (keep trailing slash, e.g., `http://localhost:3002/`) | | `PORT` | Local port for FastMCP HTTP transport (defaults to `3002`) | Store secrets securely Avoid committing `.env` to source control. Use your team’s secret manager in production and rotate credentials if they appear in logs or terminal history. 6. ## Run the FastMCP server locally [Section titled “Run the FastMCP server locally”](#run-the-fastmcp-server-locally) Start the server so it can accept authenticated MCP requests at `/mcp`. Terminal
```bash
source venv/bin/activate
python server.py
```
When the server boots successfully, you’ll see FastMCP announce the HTTP transport and listen on `http://localhost:3002/`, ready to enforce Scalekit-issued tokens.  7. ## Connect with an MCP client [Section titled “Connect with an MCP client”](#connect-with-an-mcp-client) Use any MCP-compatible client to exercise the todo tools with scoped tokens. During development, the MCP Inspector demonstrates how the Scalekit provider enforces scopes end-to-end. Terminal
```bash
npx @modelcontextprotocol/inspector@latest
```
In the Inspector UI, point the client to `http://localhost:3002/mcp` and click **Connect**. The client initiates OAuth authentication with Scalekit. After successful authentication, run any tool—the server exposes `create_todo`, `list_todos`, `get_todo`, `update_todo`, and `delete_todo`.  Once you’re satisfied with the quickstart example, extend `server.py` with your own FastMCP tools or replace the in-memory store with your production data source. Scalekit’s provider handles authentication for any toolset you add.
---
# DOCUMENT BOUNDARY
---
# New to MCP?
> Lock down MCP connections with OAuth 2.1 so agents get only the access they need
AI systems are moving beyond chatbots to agents that act in the real world. They handle sensitive data and run complex workflows. As they grow, they need a secure, standard way to connect. The Model Context Protocol (MCP) provides that standard. It defines how AI applications safely discover and use external tools and data.  MCP incorporates OAuth 2.1 authorization mechanisms at the transport level. This enables MCP clients to make secure requests to restricted MCP servers on behalf of resource owners. | Features | Benefit | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Industry standard | Well-established authorization framework with extensive tooling and ecosystem support | | Security best practices | Incorporates improvements over OAuth 2.0, removing deprecated flows and enforcing security measures like PKCE | | Multiple grant types | Supports different use cases: **Authorization code** for human user scenarios and **Client credentials** for machine-to-machine integrations | | Ecosystem compatibility | Integrates with existing identity providers and authorization servers | ## Complete MCP OAuth 2.1 flow [Section titled “Complete MCP OAuth 2.1 flow”](#complete-mcp-oauth-21-flow) Here’s the complete end-to-end authorization flow showing all phases from discovery to token refresh in a single sequence diagram:  ### Understanding the MCP authorization flow [Section titled “Understanding the MCP authorization flow”](#understanding-the-mcp-authorization-flow) MCP OAuth 2.1 provides secure, standardized authorization for AI agents accessing protected resources. The flow establishes trust, authenticates users, authorizes access, and maintains security throughout the session lifecycle by building each phase on the previous one.
---
# DOCUMENT BOUNDARY
---
# Production readiness checklist
> A focused checklist for launching your MCP server authentication, with emphasis on custom domain and branding for a production-grade OAuth consent experience.
As you prepare to launch MCP server authentication to production, verify these items before going live. ## Production environment [Section titled “Production environment”](#production-environment) **Verify production environment configuration** Confirm that your environment URL (`SCALEKIT_ENVIRONMENT_URL`), client ID (`SCALEKIT_CLIENT_ID`), and client secret (`SCALEKIT_CLIENT_SECRET`) are correctly set for production, not dev or staging. ## Custom domain (CNAME) [Section titled “Custom domain (CNAME)”](#custom-domain-cname) Configuring a custom domain is the highest-impact step for MCP auth. Without it, the OAuth consent screen your users see during authorization displays `yourapp.scalekit.com` (Scalekit’s default domain) instead of your own brand. Complete this section before you test any end-to-end auth flows in production. **Configure a custom domain in the Scalekit dashboard** Go to **Dashboard > Auth for SaaS > Customization > Custom Domain** and follow the CNAME setup instructions. CNAME configuration is available only in production environments. See [Branded custom domains](/guides/custom-domain/) for step-by-step instructions. **Verify SSL certificate provisioning** After CNAME verification, Scalekit automatically provisions an SSL certificate. Click **Check** in **Dashboard > Auth for SaaS > Customization > Custom Domain** to confirm status. Provisioning can take up to 24 hours. Contact if it takes longer. **Update customer-facing authorization URLs to use your custom domain** Backend API calls work with either URL, but the authorization URL and any other endpoints your users interact with must use your custom domain (for example, `mcp.yourapp.com`) for branding to take effect. Update those URLs in your application code after CNAME setup is complete. **Confirm the consent screen shows your branded domain** Open an incognito window, trigger an authorization flow, and verify the OAuth consent screen shows your custom domain (for example, `mcp.yourapp.com`) and not the default Scalekit URL. ## Consent screen branding [Section titled “Consent screen branding”](#consent-screen-branding) **Upload your logo and set brand colors** Go to **Dashboard > Auth for SaaS > Customization > Branding** to upload your logo, set a favicon, and configure background colors. This is what users see during the OAuth authorization flow. **Set a recognizable MCP server name** When registering your MCP server in **Dashboard > MCP Servers**, provide a name that users will recognize (for example, `Acme Calendar`, not `mcp-prod-v2`). This name appears on the consent page that MCP hosts display to users when they authorize access. ## Bring your own auth (if applicable) [Section titled “Bring your own auth (if applicable)”](#bring-your-own-auth-if-applicable) If you are using a federated authentication setup where Scalekit acts as the OAuth 2.1 layer but delegates user authentication to your existing system, verify these additional items. **Configure your login endpoint URL in the Scalekit dashboard** Scalekit redirects users to your login endpoint with a `login_request_id` and `state` parameter. Confirm the endpoint URL is correctly set for your production environment. **Verify your login endpoint handles the `login_request_id` and `state` parameters** Your login page must capture both parameters from the redirect and pass them through the authentication flow. Missing either parameter breaks the callback handshake. **Test the backend-to-backend user handoff** After authenticating a user, your system POSTs user attributes to Scalekit at `/api/v1/connections//auth-requests//user`. Verify this call succeeds with production credentials and that the `connection_id` (starts with `conn_`) is correct for your production MCP server. **Verify the state parameter in your callback redirect** After the user handoff, your system redirects back to Scalekit’s callback URL with the `state` value from step 1. Confirm the values match exactly. Mismatched state is silently rejected and breaks the flow. **Test the complete federated flow end-to-end** Trigger a full authorization flow from an MCP client through your login page, the user handoff API call, and the callback redirect, and verify the MCP client receives a valid access token at the end. See [Bring your own auth](/authenticate/mcp/custom-auth/) for implementation details. ## Core auth flows [Section titled “Core auth flows”](#core-auth-flows) **Test the human → MCP authorization flow end-to-end** After CNAME and branding are configured, trigger a complete authorization code flow: from the initial tool call through the `401` challenge, consent screen, token exchange, and authorized response. Run this in production with your live credentials. **Test the agent → MCP client credentials flow** Verify that API clients can obtain tokens and call MCP tools successfully. Confirm that client credentials are stored in environment variables or a secrets manager, not hardcoded. ## Monitoring [Section titled “Monitoring”](#monitoring) **Enable auth logs and set up alerts** Monitor **Dashboard > Auth Logs** for repeated `401` errors, invalid scope requests, and token failures after launch. Set up alerts for unusual activity patterns. After launch, use [Auth logs](/guides/dashboard/auth-logs/) to debug authentication issues and review the [MCP auth troubleshooting guide](/authenticate/mcp/troubleshooting/) for common problems.
---
# DOCUMENT BOUNDARY
---
# Managing MCP Clients
> Manage MCP clients by viewing registered MCP clients, tracking user consent, and revoking access to your MCP servers.
To maintain security and control over your MCP Server, you need to manage which client applications can access it. Scalekit provides several ways for clients to connect, including automatic registration for modern apps and manual pre-registration for custom or trusted clients. This guide covers the different types of MCP clients and shows you how to: * View all registered clients * See which users have granted consent to a client * Revoke user access for any client There are three main categories of MCP Clients that can interact with your MCP Server: ## 1. Automatic registration with DCR [Section titled “1. Automatic registration with DCR”](#1-automatic-registration-with-dcr) These are MCP Clients that automatically register themselves as OAuth clients. Most modern MCP clients, such as Claude Desktop, OpenAI, VS Code, and Cursor, support Dynamic Client Registration (DCR). They initiate the registration process and start the OAuth Authorization flow with the Scalekit server to obtain an access token without requiring manual configuration. During the consent flow, users see your **environment domain** as the requesting identifier - not “Scalekit” and not your application name. This is by design: the domain identifies the authorization server handling the request, similar to how Google OAuth shows the requesting domain. To display a custom branded domain, configure a [custom domain](/guides/custom-domain/) for your Scalekit environment. ## 2. Manual client pre-registration [Section titled “2. Manual client pre-registration”](#2-manual-client-pre-registration) These are MCP Clients that you manually register in the Scalekit Dashboard. This is useful when you want to restrict access to specific, pre-approved clients or when you are building a custom client that requires fixed credentials. You can create OAuth clients that can either act as themselves or on behalf of the user. ### How to pre-register a client [Section titled “How to pre-register a client”](#how-to-pre-register-a-client) If you need to manually register an MCP Client, you can do so in the Scalekit Dashboard. 1. Navigate to the **Clients** section of your MCP Server. 2. Click the **Create Client** button.  **Configuration:** * **Client name**: A display name (e.g., “My Custom Client”). * **Redirect URI**: The URL where the client will redirect users after authorization. 3. **Choosing the right OAuth flow:** * **For Client Credentials Flow**: Leave the Redirect URI field empty. Your application will authenticate using only the `client_id` and `client_secret`. This is suitable for server-to-server communication. * **For Authorization Code Grant Flow**: Provide one or more Redirect URIs where users will be redirected after granting consent. This is required for user-facing applications that need to act on behalf of users. **Cross-App Access (XAA):** XAA doesn’t require any explicit setting - your static clients by default support cross-app access under enterprise plan. Once the client is created, you will receive a `client_id` and `client_secret` to configure in your application.  ### 2.1 OAuth client credential flow [Section titled “2.1 OAuth client credential flow”](#21-oauth-client-credential-flow) Use this flow when your MCP Client needs to act on its own behalf rather than on behalf of a specific user. This is ideal for machine-to-machine communication scenarios. **When to use:** * Backend services or server-side applications * Automated scripts or batch processes * System integrations that don’t require user interaction * Applications that need to access resources without user context **Characteristics:** * No user interaction required * No redirect URI needed * Client authenticates using `client_id` and `client_secret` * Access token represents the client itself ### 2.2 OAuth authorization code grant flow [Section titled “2.2 OAuth authorization code grant flow”](#22-oauth-authorization-code-grant-flow) Use this flow when your MCP Client needs to act on behalf of a user. This is the standard OAuth flow that requires user consent. **When to use:** * User-facing applications (web, desktop, or mobile) * Applications that need to access user-specific resources * Scenarios requiring explicit user consent * Applications where actions should be attributed to specific users **Characteristics:** * Requires user authentication and consent * Redirect URI is mandatory * Client receives authorization code, exchanges it for access token * Access token represents the user’s authorization ## 3. Registration via metadata URL (CIMD) [Section titled “3. Registration via metadata URL (CIMD)”](#3-registration-via-metadata-url-cimd) These are MCP Clients that support Client ID Metadata Document (CIMD), an OAuth 2.0 mechanism that allows clients to use a URL as their client identifier. When a CIMD-compatible client initiates the OAuth flow, Scalekit fetches the client’s metadata (such as name, redirect URIs, and other registration information) from the provided URL. This provides an alternative registration method without requiring manual pre-registration or Dynamic Client Registration, making it easier for clients to authenticate across different authorization servers. ## Manage registered clients [Section titled “Manage registered clients”](#manage-registered-clients) ### View all registered clients [Section titled “View all registered clients”](#view-all-registered-clients) You can view a list of all MCP Clients that have been registered with your MCP Server (both DCR and pre-registered) in the Scalekit Dashboard. 1. Go to your MCP Server in the dashboard. 2. Click on the **Clients** tab.  ### View consented users [Section titled “View consented users”](#view-consented-users) For each registered MCP Client that uses the OAuth Authorization Code Grant Flow, you can view all users who have granted consent. 1. From the **Clients** list, click on a specific client. 2. Navigate to the **Consents** tab to see the list of users who have authorized this client.  To audit the same consents from your own admin screens, list them with the Node SDK. See [Resource](/saaskit/sdks/node/resources/). ### Revoke user access [Section titled “Revoke user access”](#revoke-user-access) As an administrator, you can revoke a user’s consent for a specific MCP Client at any time. This is useful when: * A user requests to revoke access * You need to remove access for security reasons * An employee leaves the organization * You want to force re-authentication **To revoke access:** 1. Navigate to the specific MCP Client from the **Clients** list. 2. Go to the **Consents** tab. 3. Find the user whose access you want to revoke. 4. Click the **Revoke** or **Delete** action for that user. Once revoked, the user will need to go through the authorization flow again to grant consent if they want to use the MCP Client. To revoke a consent programmatically, call `revokeUserConsent` in the Node SDK. See [Resource](/saaskit/sdks/node/resources/). ### Revoke access from a public MCP client [Section titled “Revoke access from a public MCP client”](#revoke-access-from-a-public-mcp-client) On Scalekit, MCP clients registered through Dynamic Client Registration (`DCR`) or a Client ID Metadata Document (`CIMD`) are public clients: they have no client secret. Scalekit’s OAuth token revocation endpoint requires client authentication, so a direct revoke call from these clients returns `invalid_client`. That response is expected, not a misconfiguration. To revoke access, use one of the supported paths instead: * **Revoke consent from the dashboard**: revoke the user’s consent from the **Consents** tab, as described in [Revoke user access](/authenticate/mcp/managing-mcp-clients/#revoke-user-access). * **Disconnect in the client**: most MCP clients expose a **Disconnect** action that clears tokens stored on the client. This is local sign-out only; it does not revoke the grant on Scalekit. * **Revoke the session in your own system**: when you use [Bring your own auth](/authenticate/mcp/custom-auth/), revoke the user’s session in your auth system. After your MCP server rejects that session, the next request returns `401 Unauthorized` and the client must authenticate again. ### How revocation affects active access tokens [Section titled “How revocation affects active access tokens”](#how-revocation-affects-active-access-tokens) Revoking consent or ending a session stops Scalekit from issuing **new** access tokens for that user, but it does not cancel an access token that was already issued. The existing token keeps working until it expires. This is expected behavior, not a vulnerability. Scalekit issues access tokens as self-contained JWTs. Your MCP server validates each token locally against Scalekit’s public keys and does not call back to the authorization server on every request, so Scalekit cannot reach out and cancel a token that is already in circulation. Every OAuth server that issues self-contained JWTs behaves this way. The exposure is bounded by the time left on the token - its `exp` claim. To shrink or close that window, use either approach: * **Shorten the access token lifetime.** Lower the **Access token lifetime** for the MCP server at **Dashboard > MCP servers > your server > Access token lifetime** (you can also set it when you [add an MCP server](/authenticate/mcp/quickstart/); the recommended range is 300–3600 seconds). You can also set it per client. A shorter lifetime means a revoked token stops working sooner. This MCP server setting is separate from the access token lifetime configured for a Web Application - changing the Web Application setting does not affect tokens minted for this MCP server. * **Maintain a token denylist.** Validate the token with the Scalekit SDK as you do today, then check its `jti` claim against a denylist before serving the request, and reject the request when the `jti` is present. Store each revoked `jti` with a time-to-live equal to the token’s remaining lifetime - for example, a Redis key that expires at the token’s `exp`. This gives near-immediate revocation at the cost of one lookup per request.
---
# DOCUMENT BOUNDARY
---
# Migrate to the new MCP spec
> Migrate your MCP server's auth to the MCP 2026-07-28 spec with zero downtime. Trust both issuers, then enable Resource bound issuer.
Scalekit is changing the issuer of access tokens for MCP servers. The **issuer** is the `iss` claim inside a token, and it tells your MCP server who minted the token. Today the issuer is your environment URL. The new MCP specification (2026-07-28) asks clients to check the issuer on every authorization response and to keep credentials separate for each authorization server. To support this, Scalekit gives each MCP server its own issuer, `/resources/`. The dashboard option that turns this on is called **Resource bound issuer**. This migration applies only to MCP servers registered in Scalekit in workspaces created before October 21, 2026. To check, open your MCP server in the Scalekit dashboard. If you see the **Resource bound issuer** option, your MCP server requires the migration, and this guide is relevant for you. If you do not see it, your MCP server already has Resource bound issuer turned on and you do not need to do anything. If you need any assistance or help, contact . This migration guide helps you migrate your MCP server’s auth to the new MCP specification with zero downtime. ## Migrate development first, then production [Section titled “Migrate development first, then production”](#migrate-development-first-then-production) **Resource bound issuer** is a setting on each MCP server. Complete every step for every MCP server in your development environment first. After you validate the result, repeat the same steps for every MCP server in your production environment. ## What changes [Section titled “What changes”](#what-changes) | | Before the migration | After the migration | | --------------------- | ------------------------------------------- | -------------------------------------------------- | | `iss` of new tokens | `https://example.scalekit.cloud` | `https://example.scalekit.cloud/resources/res_123` | | Tokens already issued | Keep their original `iss` until they expire | Keep their original `iss` until they expire | Old and new tokens are both in circulation for a while, so your server must trust both issuers during the migration. 1. ## Trust both issuers in your token validation [Section titled “Trust both issuers in your token validation”](#trust-both-issuers-in-your-token-validation) Find the code in your MCP server that validates access tokens. In the quickstart, it is the call that passes `issuer`. Today it passes only your environment URL. Update it to trust two issuers: your environment URL and `/resources/`. In the examples, `ENV_URL` is your environment URL and `RESOURCE_ID` is your resource ID. ### If you use a Scalekit SDK [Section titled “If you use a Scalekit SDK”](#if-you-use-a-scalekit-sdk) Update your MCP server to use the latest Scalekit SDK version, which supports trusting multiple issuers. Then add both issuers while calling the validate method. * Node.js Trust both issuers
```javascript
await scalekit.validateToken(token, {
// Before: issuer: ENV_URL
issuer: [ENV_URL, `${ENV_URL}/resources/${RESOURCE_ID}`],
audience: [RESOURCE_ID],
});
```
* Python Trust both issuers
```python
options = TokenValidationOptions(
# Before: issuer=ENV_URL
issuer=[ENV_URL, f"{ENV_URL}/resources/{RESOURCE_ID}"],
audience=[RESOURCE_ID],
)
scalekit_client.validate_token(token, options=options)
```
* Go Trust both issuers
```go
ok, err := scalekitClient.ValidateTokenWithOptions(ctx, token, &scalekit.ValidateTokenOptions{
// Before: Issuer: envURL
Issuers: []string{envURL, envURL + "/resources/" + RESOURCE_ID},
Audience: []string{RESOURCE_ID},
})
if err != nil || !ok {
// Reject the request
}
```
* Java Trust both issuers
```java
TokenValidationOptions options = TokenValidationOptions.builder()
// Before: .issuer(envUrl)
.issuers(List.of(envUrl, envUrl + "/resources/" + RESOURCE_ID))
.audience(List.of(RESOURCE_ID))
.build();
boolean isValid = scalekitClient.authentication().validateAccessToken(token, options);
if (!isValid) {
// Reject the request
}
```
### If you use FastMCP [Section titled “If you use FastMCP”](#if-you-use-fastmcp) The Scalekit provider in FastMCP already trusts both your environment URL and `/resources/`, so you do not need to change your validation code. Continue with [Enable Resource bound issuer](#enable-resource-bound-issuer). Make sure you are using the latest version of FastMCP. ### If you use your own JWT validator [Section titled “If you use your own JWT validator”](#if-you-use-your-own-jwt-validator) Configure your validator to trust exactly two `iss` values, and reject any other issuer. Most JWT libraries accept a list of allowed issuers. 2. ## Release your MCP server [Section titled “Release your MCP server”](#release-your-mcp-server) Release the change. Then check that both kinds of tokens work: * **A token issued before the release**: call a tool from a session that was authorized before the release, without authorizing again. The request should still succeed. * **A new token**: disconnect your MCP client, for example MCP Inspector, and connect again so that it authorizes again. Call a tool. The request should succeed. Nothing changes for your users yet, because tokens still carry your environment URL. 3. ## Enable Resource bound issuer [Section titled “Enable Resource bound issuer”](#enable-resource-bound-issuer) Enable the option in the Scalekit dashboard: 1. Go to **MCP servers** and select your MCP server. 2. Enable **Resource bound issuer**. 3. Read the confirmation dialog. It explains that tokens issued from now on carry `/resources/` as the `iss` claim. Confirm after you have read this guide.  Repeat the checks from the previous step. Existing tokens must still work. For a new token, the `iss` claim should be `/resources/`, and your MCP server should accept it. Do not disable Resource bound issuer After you enable it, do not disable it. Switching back changes the issuer your clients see, which can break connected clients. ## Frequently asked questions [Section titled “Frequently asked questions”](#frequently-asked-questions) ## Why Scalekit is making this change [Section titled “Why Scalekit is making this change”](#why-scalekit-is-making-this-change) The Model Context Protocol (MCP) [2026-07-28 specification](https://blog.modelcontextprotocol.io/posts/2026-07-28/) strengthens issuer checks. Authorization servers should return the `iss` parameter per RFC 9207, and clients must validate it before redeeming a code. This closes an authorization-server mix-up hole. The specification also binds client credentials to the issuer that minted them. To support these checks, each MCP server in Scalekit has its own issuer. That is why your MCP server must trust the server’s own issuer. If a token is rejected unexpectedly, see [Troubleshooting MCP auth](/authenticate/mcp/troubleshooting/).
---
# DOCUMENT BOUNDARY
---
# Agent / Machine interacting with MCP Server
> Learn how an autonomous agent or machine securely authenticates with an MCP Server using OAuth 2.1 Client Credentials flow in Scalekit.
An **autonomous agent** or any **machine-to-machine process** can directly interact with an **MCP Server** secured by Scalekit. In this model, the agent acts as a **confidential OAuth client**, authenticated using a `client_id` and `client_secret` issued by Scalekit. This topology uses the **OAuth 2.1 Client Credentials flow**, allowing the agent to obtain an access token without user interaction. Tokens are scoped and time-bound, ensuring secure and auditable automation between services. *** ## Authorization Sequence [Section titled “Authorization Sequence”](#authorization-sequence)  *** ## How It Works [Section titled “How It Works”](#how-it-works) **Client Registration** Before an agent can request tokens, you must create a **Machine-to-Machine (M2M) client** for your MCP Server in Scalekit. Steps to create a client: 1. Navigate to **Dashboard ? MCP Servers** and select your MCP Server. Go to the **Clients** tab.  2. Click **Create Client**.  3. Copy the **client_id** and **client_secret** immediately - the secret will not be shown again.  4. Optionally, set scopes (e.g., `todo:read`, `todo:write`) that correspond to the permissions configured for your MCP Server. Hit **Save** *** ## Requesting an Access Token [Section titled “Requesting an Access Token”](#requesting-an-access-token) Once you have the client credentials, the agent can request a token directly from the Scalekit Authorization Server: Terminal
```bash
curl --location '{{env_url}}/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={{client_id}}' \
--data-urlencode 'client_secret={{secret_value}}' \
--data-urlencode 'scope=todo:read todo:write'
```
Scalekit responds with a JSON payload similar to:
```json
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "todo:read todo:write"
}
```
Use the `access_token` in the `Authorization` header when calling your MCP Server’s endpoint. *** ## Try It Yourself [Section titled “Try It Yourself”](#try-it-yourself) If you’d like to simulate this flow, use the same **FastMCP Todo Server** from the [FastMCP Example](/authenticate/mcp/fastmcp-quickstart). Create an **M2M client** in the Scalekit Dashboard and run your token request using `curl` or programmatically within your agent. Once the token is obtained, attach it as a Bearer token in the `Authorization` header when calling your MCP Server’s tools.
---
# DOCUMENT BOUNDARY
---
# Human interacting with MCP Server
> Learn how a human authenticates with an MCP Server via OAuth 2.1 when using MCP-compliant hosts such as ChatGPT, Claude, VSCode, or Windsurf.
When a human uses a compliant MCP host, that host acts as the OAuth client. It initiates authorization with the Scalekit Authorization Server, obtains a scoped access token, and interacts securely with the MCP Server on behalf of the user. This topology represents the most common interaction model for real-world MCP usecases - **humans interacting with an MCP**, while Scalekit ensures tokens are valid, scoped, and auditable. *** ## Authorization Sequence [Section titled “Authorization Sequence”](#authorization-sequence)  *** ## How It Works [Section titled “How It Works”](#how-it-works) 1. **Initiation** ? The human configures an MCP server in their MCP client. 2. **Challenge** ? The MCP Server responds with an HTTP `401` containing a `WWW-Authenticate` header that points to the Scalekit Authorization Server. 3. **Authorization Flow** ? The MCP Client opens the user’s browser to initiate the OAuth 2.1 authorization flow. During this step, the Scalekit Authorization Server handles user authentication through Passwordless, Passkeys, Social login providers (like Google, GitHub, or LinkedIn), or Enterprise SSO integrations (such as Okta, Microsoft Entra ID, or ADFS). The user is then prompted to grant consent for the requested scopes. Once approved, Scalekit returns an authorization code, which the MCP Client exchanges for an access token. 4. **Token Issuance** ? Scalekit issues an OAuth 2.1 access token containing claims and scopes (for example, `todo:read`, `calendar:write`) that represent the user’s permissions. 5. **Authorized Request** ? The client calls the MCP Server again, now attaching the Bearer token in the `Authorization` header. 6. **Validation and Execution** ? The MCP Server validates the token issued by scalekit and executes the requested tool. *** ## Try It Yourself [Section titled “Try It Yourself”](#try-it-yourself) Head to the **[FastMCP Examples section](/authenticate/mcp/fastmcp-quickstart)** to experience this topology in action. There you’ll register a FastMCP server, configure Scalekit Auth, and observe token issuance and validation end-to-end.
---
# DOCUMENT BOUNDARY
---
# MCP Server interacting with MCPs / APIs
> Understand how an MCP Server integrates with internal systems, other MCP servers, or external APIs using secure tokens or API keys.
In real-world scenarios, an **MCP Server** often needs to make backend calls - to your **own APIs**, to **another MCP Server**, or to **external APIs** such as CRM, ticketing, or SaaS tools. This page explains three secure ways to perform these downstream integrations, each corresponding to a different trust boundary and authorization pattern. ## 1. Using API Keys or Custom Tokens [Section titled “1. Using API Keys or Custom Tokens”](#1-using-api-keys-or-custom-tokens) Your MCP Server can communicate with internal or external backend systems that have their own authorization servers or API key?based access. In this setup, the MCP Server manages its own credentials securely (for example, an environment variable, vault, or secrets manager) and injects them when making downstream calls.  ### Example [Section titled “Example”](#example) * The MCP Server stores an API key as `EXTERNAL_API_KEY` in environment variables. * When a tool (e.g., `get_weather_data`) is called, your MCP server attaches the key in the request. * The backend API validates the key and responds with data. *** ## 2. Interacting with Another MCP Server autonomously [Section titled “2. Interacting with Another MCP Server autonomously”](#2-interacting-with-another-mcp-server-autonomously) If you have two MCP Servers that need to communicate - for example, `crm-mcp` calling tools from `tickets-mcp` - you can follow the same authentication pattern described in the [Agent ? MCP](/authenticate/mcp/topologies/agent-mcp/) topology. The calling MCP Server (in this case, `crm-mcp`) acts as an **autonomous agent**, authenticating with the receiving MCP Server via **OAuth 2.1 Client Credentials Flow**. Once the token is issued by Scalekit, the calling MCP uses it to call tools exposed by the second MCP Server.  You can find a detailed explanation of this topology in [this section](/authenticate/mcp/topologies/agent-mcp). *** ## 3. Cascading the Same Token to Downstream Systems [Section titled “3. Cascading the Same Token to Downstream Systems”](#3-cascading-the-same-token-to-downstream-systems) In some cases, you may want your MCP Server to forward (or “cascade”) the **same access token** it received from the client - for example, when your backend system lies within the same trust boundary as the Scalekit Authorization Server and can validate the token based on its issuer, scopes, and expiry.  ### When to Use This Pattern [Section titled “When to Use This Pattern”](#when-to-use-this-pattern) * Both systems (MCP Server and backend MCP/API) trust **the same Authorization Server** (Scalekit). * The backend API can validate JWTs using public keys or JWKS URL. * Scopes and issuer claims (`iss`, `scope`, `exp`) are sufficient to determine access.
---
# DOCUMENT BOUNDARY
---
# Troubleshooting MCP auth
> Troubleshooting guide for common errors while adding auth for MCP Servers
Use this guide when you use Scalekit as the authentication server for your MCP servers and a client fails to connect, a request stalls, or the authentication handshake breaks. Start with the category that matches your symptom, then open the matching scenario. Most issues fall into configuration and setup, CORS and network access, or client-specific behavior. Each scenario explains the cause and the fix. ## Configuration and setup [Section titled “Configuration and setup”](#configuration-and-setup) ## CORS and network access [Section titled “CORS and network access”](#cors-and-network-access) ## Client-specific issues [Section titled “Client-specific issues”](#client-specific-issues) ## Best practices [Section titled “Best practices”](#best-practices) Follow these best practices to avoid common issues and maintain a robust MCP authentication setup: 1. **Use separate Scalekit environments** for development and production to prevent configuration conflicts 2. **Register MCP servers with environment-specific domains:** * Development: `https://mcp-dev.yourdomain.com/` * Production: `https://mcp.yourdomain.com/` 3. **Update your MCP client configuration** to point to the correct Scalekit environment for each deployment 4. **Test authentication independently** in each environment before you deploy to production 5. **Monitor authentication logs** in **Dashboard > Authentication > Logs** to identify and resolve issues quickly 6. **Keep callback URLs updated** whenever you change domains or ports ## Get help [Section titled “Get help”](#get-help) If none of the scenarios resolve the issue, open **Dashboard > Authentication > Logs** and review the authorization and token requests for the failing attempt. When you contact [support](mailto:support@scalekit.com), include: * The failing `client_id` and the MCP server `resource_id` * The MCP client and transport (for example, a Claude Desktop custom connector or `mcp-remote`) * The full error text and the approximate timestamp of the attempt * The steps that reproduce the failure
---
# DOCUMENT BOUNDARY
---
# Add auth to xmcp server
> Build an MCP server with xmcp framework and Scalekit OAuth 2.1 authentication. xmcp handles transport, routing, and bundling so you focus on tools.
This guide shows you how to build an MCP server with [xmcp](https://xmcp.dev) and secure it with Scalekit OAuth 2.1. xmcp is a TypeScript MCP framework that handles transport setup, bundling, and hot reload — you write tools as plain functions and add auth via a middleware file. Use this quickstart when you want a framework that manages MCP protocol details for you. xmcp gives you file-based routing for tools, built-in Streamable HTTP transport, and a middleware convention that keeps auth separate from business logic. The full code is available on [GitHub](https://github.com/scalekit-developers/xmcp-scalekit-example). **Prerequisites** * A [Scalekit account](https://app.scalekit.com) with permission to manage MCP servers * **Node.js 18+** installed locally * Basic understanding of TypeScript and OAuth 1. ## Register your MCP server in Scalekit [Section titled “Register your MCP server in Scalekit”](#register-your-mcp-server-in-scalekit) Create a protected resource entry so Scalekit can issue and validate tokens for your server. 1. Navigate to **[Dashboard](https://app.scalekit.com) > MCP Servers > Add MCP Server**. 2. Enter a descriptive name (for example, `xmcp Demo`). 3. Set **Server URL** to `http://localhost:3001`. 4. Ensure **Allow dynamic client registration** is checked — this is required for MCP clients like Claude Desktop and Cursor to connect automatically. 5. Click **Save** to create the server. After saving, note the **Resource ID** shown below the server name (for example, `res_...`). You’ll need it in the next step. 2. ## Create your project [Section titled “Create your project”](#create-your-project) Scaffold a new xmcp project and add the dependencies for Scalekit authentication. Terminal
```bash
mkdir xmcp-scalekit-example
cd xmcp-scalekit-example
```
Create `package.json`: package.json
```json
1
{
2
"name": "xmcp-scalekit-example",
3
"private": true,
4
"scripts": {
5
"dev": "xmcp dev",
6
"build": "xmcp build",
7
"start": "node dist/http.js"
8
},
9
"dependencies": {
10
"xmcp": "^0.6.10",
11
"@scalekit-sdk/node": "^2.6.2",
12
"jose": "^5.2.0",
13
"express": "^4.22.1",
14
"zod": "^4.0.10"
15
},
16
"devDependencies": {
17
"@types/express": "^4.17.25",
18
"@types/node": "^22.19.2",
19
"typescript": "^5.9.3"
20
}
21
}
```
Install dependencies: Terminal
```bash
npm install
```
3. ## Configure environment variables [Section titled “Configure environment variables”](#configure-environment-variables) Create a `.env` file with your Scalekit credentials from step 1. Terminal
```bash
cat <<'EOF' > .env
SCALEKIT_ENVIRONMENT_URL=https://.scalekit.com
SCALEKIT_CLIENT_ID=
SCALEKIT_CLIENT_SECRET=
SCALEKIT_RESOURCE_ID=
BASE_URL=http://localhost:3001
PORT=3001
EOF
open .env
```
| Variable | Description | | -------------------------- | ---------------------------------------------------------------------------------------------- | | `SCALEKIT_ENVIRONMENT_URL` | Your Scalekit environment URL from **Dashboard > Settings > API Credentials** | | `SCALEKIT_CLIENT_ID` | Client ID from **Dashboard > Settings > API Credentials** | | `SCALEKIT_CLIENT_SECRET` | Client secret from **Dashboard > Settings > API Credentials** | | `SCALEKIT_RESOURCE_ID` | Resource ID from **Dashboard > MCP Servers** (the `res_...` value shown below the server name) | | `BASE_URL` | Public URL where your server is reachable. Must match the Server URL registered in Scalekit | | `PORT` | Local port for the server | Resource ID is required Without `SCALEKIT_RESOURCE_ID`, the server cannot serve the resource-specific authorization server metadata that includes the `registration_endpoint`. MCP clients that rely on Dynamic Client Registration (DCR) — including Claude Desktop and Cursor — will fail to connect. 4. ## Enable Streamable HTTP transport [Section titled “Enable Streamable HTTP transport”](#enable-streamable-http-transport) Create `xmcp.config.ts` at the project root to enable Streamable HTTP mode. By default xmcp uses stdio; setting `http: true` starts an Express-based HTTP server. xmcp.config.ts
```typescript
import { XmcpConfig } from "xmcp";
const config: XmcpConfig = {
http: true,
paths: {
prompts: false,
resources: false,
},
};
export default config;
```
5. ## Add the Scalekit auth provider [Section titled “Add the Scalekit auth provider”](#add-the-scalekit-auth-provider) This server validates tokens whose issuer (`iss`) is `/resources/`. If you see the **Resource bound issuer** option on your MCP server in the Scalekit dashboard, your workspace was created before October 21, 2026. Until you enable that option, your tokens carry your environment URL as the issuer, and this server rejects them with a `401`. Follow [Migrate to the new MCP spec](/authenticate/mcp/migrate-to-2026-07-28-mcp-spec/) first. Create `src/lib/scalekit-auth.ts` — this is the auth provider that handles JWT verification and OAuth discovery endpoints. The provider returns an xmcp `Middleware` object with a `router` (for discovery endpoints) and a `middleware` (for token validation on `/mcp`). src/lib/scalekit-auth.ts
```typescript
1
import {
2
Router,
3
Request,
4
Response,
5
NextFunction,
6
type RequestHandler,
7
} from "express";
8
import { createContext, type Middleware } from "xmcp";
9
import { createRemoteJWKSet, jwtVerify, errors } from "jose";
10
import { Scalekit } from "@scalekit-sdk/node";
11
12
// --- Types ---
13
14
export interface ScalekitConfig {
15
readonly environmentUrl: string;
16
readonly clientId: string;
17
readonly clientSecret: string;
18
readonly baseURL: string;
19
readonly resourceId?: string;
20
readonly docsURL?: string;
21
readonly scopes?: readonly string[];
22
}
23
24
export interface JWTClaims {
25
readonly sub: string;
26
readonly iss: string;
27
readonly aud?: string | readonly string[];
28
readonly exp: number;
29
readonly iat: number;
30
readonly scope?: string;
31
readonly sid?: string;
32
readonly org_id?: string;
33
}
34
35
export interface Session {
36
readonly userId: string;
37
readonly scopes: readonly string[];
38
readonly organizationId?: string;
39
readonly expiresAt: Date;
40
readonly issuedAt: Date;
41
readonly claims: JWTClaims;
42
}
43
44
interface SessionContext {
45
session: Session | null;
46
}
47
48
interface ClientContext {
49
client: Scalekit;
50
}
51
52
const sessionContext = createContext({
53
name: "scalekit-context-session",
54
});
55
56
const clientContext = createContext({
57
name: "scalekit-context-client",
58
});
59
60
// --- Public accessors (call from tools) ---
61
62
export function getSession(): Session {
63
const ctx = sessionContext.getContext();
64
if (!ctx.session) {
65
throw new Error(
66
"[Scalekit] No session. Is the request authenticated?"
67
);
68
}
69
return ctx.session;
70
}
71
72
export function getClient(): Scalekit {
73
const { client } = clientContext.getContext();
74
if (!client) {
75
throw new Error(
76
"[Scalekit] Client not initialized."
77
);
78
}
79
return client;
80
}
81
82
// --- JWT helpers ---
83
84
async function verifyScalekitToken(
85
token: string,
86
jwksUrl: URL,
87
issuer: string
88
) {
89
const JWKS = createRemoteJWKSet(jwksUrl);
90
const { payload } = await jwtVerify(token, JWKS, {
91
issuer,
92
clockTolerance: 30,
93
});
94
if (!payload.sub) throw new Error("Missing sub claim");
95
return payload as unknown as JWTClaims;
96
}
97
98
function claimsToSession(claims: JWTClaims): Session {
99
return {
100
userId: claims.sub,
101
scopes: claims.scope ? claims.scope.split(" ") : [],
102
organizationId: claims.org_id,
103
expiresAt: new Date(claims.exp * 1000),
104
issuedAt: new Date(claims.iat * 1000),
105
claims,
106
};
107
}
108
109
function extractBearerToken(
110
header: string | undefined
111
): string | null {
112
if (!header) return null;
113
const parts = header.split(" ");
114
if (parts.length !== 2 || parts[0].toLowerCase() !== "bearer")
115
return null;
116
return parts[1];
117
}
118
119
// --- Provider factory ---
120
121
export function scalekitProvider(
122
config: ScalekitConfig
123
): Middleware {
124
const client = new Scalekit(
125
config.environmentUrl,
126
config.clientId,
127
config.clientSecret
128
);
129
130
clientContext.provider({ client }, () => {});
131
sessionContext.provider({ session: null }, () => {});
132
133
const envUrl = config.environmentUrl.replace(/\/$/, "");
134
const authServerBase = config.resourceId
135
? `${envUrl}/resources/${config.resourceId}`
136
: envUrl;
137
138
// Pre-fetch JWKS URI — try OAuth AS metadata first.
139
// Resource-specific paths serve /.well-known/oauth-authorization-server
140
// but NOT /.well-known/openid-configuration.
141
let resolvedJwksUri: URL | null = null;
142
(async () => {
143
try {
144
const urls = [
145
`${authServerBase}/.well-known/oauth-authorization-server`,
146
`${authServerBase}/.well-known/openid-configuration`,
147
];
148
for (const url of urls) {
149
const response = await fetch(url);
150
if (response.ok) {
151
const meta = (await response.json()) as {
152
jwks_uri?: string;
153
};
154
if (meta.jwks_uri) {
155
resolvedJwksUri = new URL(meta.jwks_uri);
156
console.log(
157
"[Scalekit] Resolved JWKS URI:",
158
resolvedJwksUri.toString()
159
);
160
return;
161
}
162
}
163
}
164
} catch (e) {
165
console.warn("[Scalekit] Could not pre-fetch JWKS URI:", e);
166
}
167
})();
168
169
return {
170
middleware: buildMiddleware(
171
config,
172
authServerBase,
173
() => resolvedJwksUri
174
),
175
router: buildRouter(config, authServerBase),
176
};
177
}
178
179
// --- Router (discovery endpoints) ---
180
181
function buildRouter(
182
config: ScalekitConfig,
183
authServerBase: string
184
): Router {
185
const router = Router();
186
const baseUrl = config.baseURL.replace(/\/$/, "");
187
188
// RFC 9728: Protected Resource Metadata
189
router.get(
190
"/.well-known/oauth-protected-resource",
191
(_req: Request, res: Response) => {
192
res.json({
193
resource: baseUrl,
194
authorization_servers: [authServerBase],
195
bearer_methods_supported: ["header"],
196
...(config.scopes &&
197
config.scopes.length > 0 && {
198
scopes_supported: config.scopes,
199
}),
200
});
201
}
202
);
203
204
// RFC 8414: Authorization Server Metadata (proxied from Scalekit)
205
// Tries /.well-known/oauth-authorization-server first because
206
// resource-specific paths include registration_endpoint for DCR.
207
router.get(
208
"/.well-known/oauth-authorization-server",
209
async (_req: Request, res: Response) => {
210
try {
211
const asUrl = `${authServerBase}/.well-known/oauth-authorization-server`;
212
const asRes = await fetch(asUrl);
213
if (asRes.ok) {
214
res.json(await asRes.json());
215
return;
216
}
217
const oidcUrl = `${authServerBase}/.well-known/openid-configuration`;
218
const oidcRes = await fetch(oidcUrl);
219
if (oidcRes.ok) {
220
res.json(await oidcRes.json());
221
return;
222
}
223
res.status(502).json({
224
error: "Failed to fetch authorization server metadata",
225
});
226
} catch {
227
res.status(502).json({
228
error: "Failed to fetch authorization server metadata",
229
});
230
}
231
}
232
);
233
234
return router;
235
}
236
237
// --- Middleware (token validation) ---
238
239
function buildMiddleware(
240
config: ScalekitConfig,
241
authServerBase: string,
242
getJwksUri: () => URL | null
243
): RequestHandler {
244
const wwwAuth =
245
'Bearer resource_metadata="/.well-known/oauth-protected-resource"';
246
247
return async (
248
req: Request,
249
res: Response,
250
next: NextFunction
251
) => {
252
if (!req.path.startsWith("/mcp")) {
253
next();
254
return;
255
}
256
257
const token = extractBearerToken(req.headers.authorization);
258
if (!token) {
259
res.setHeader("WWW-Authenticate", wwwAuth);
260
res.status(401).json({
261
error: "unauthorized",
262
error_description: "Missing or invalid bearer token",
263
});
264
return;
265
}
266
267
try {
268
const jwksUrl =
269
getJwksUri() ||
270
new URL(`${authServerBase}/.well-known/jwks`);
271
272
// Validate against authServerBase, the server's own issuer:
273
// environmentUrl/resources/. Workspaces created before
274
// October 21, 2026: see the migration guide first.
275
const claims = await verifyScalekitToken(
276
token,
277
jwksUrl,
278
authServerBase
279
);
280
281
const session = claimsToSession(claims);
282
sessionContext.provider({ session }, () => next());
283
} catch {
284
res.setHeader(
285
"WWW-Authenticate",
286
`${wwwAuth}, error="invalid_token"`
287
);
288
res.status(401).json({
289
error: "invalid_token",
290
error_description: "Token verification failed",
291
});
292
}
293
};
294
}
```
Three details that are easy to get wrong: * **JWKS resolution:** Resource-specific paths on Scalekit serve `/.well-known/oauth-authorization-server` but return 404 for `/.well-known/openid-configuration`. The provider tries both in order. * **AS metadata proxy:** The resource-specific `oauth-authorization-server` response includes the `registration_endpoint` that DCR clients need. The environment-level `openid-configuration` does not. * **Issuer validation:** The middleware validates against `authServerBase`, which is `/resources/`, the server’s own issuer. The verifier uses `jose`, whose `issuer` option accepts an array of accepted issuers. For MCP servers in workspaces created before October 21, 2026, first [migrate to the new MCP spec](/authenticate/mcp/migrate-to-2026-07-28-mcp-spec/). 6. ## Wire the middleware [Section titled “Wire the middleware”](#wire-the-middleware) Create `src/middleware.ts` — this is the file xmcp looks for to apply auth middleware to all requests. src/middleware.ts
```typescript
import { scalekitProvider } from "./lib/scalekit-auth";
export default scalekitProvider({
environmentUrl: process.env.SCALEKIT_ENVIRONMENT_URL!,
clientId: process.env.SCALEKIT_CLIENT_ID!,
clientSecret: process.env.SCALEKIT_CLIENT_SECRET!,
baseURL: process.env.BASE_URL || "http://localhost:3001",
resourceId: process.env.SCALEKIT_RESOURCE_ID,
scopes: ["openid", "profile", "email"],
});
```
7. ## Add tools [Section titled “Add tools”](#add-tools) xmcp uses file-based routing — each file in `src/tools/` becomes an MCP tool. Create two tools that use the authenticated session. src/tools/whoami.ts
```typescript
1
import { type ToolMetadata } from "xmcp";
2
import { getSession } from "../lib/scalekit-auth";
3
4
export const metadata: ToolMetadata = {
5
name: "whoami",
6
description:
7
"Returns the authenticated user's session information",
8
};
9
10
export default function whoami(): string {
11
const session = getSession();
12
return JSON.stringify(
13
{
14
userId: session.userId,
15
scopes: session.scopes,
16
organizationId: session.organizationId || "N/A",
17
expiresAt: session.expiresAt.toISOString(),
18
issuedAt: session.issuedAt.toISOString(),
19
},
20
null,
21
2
22
);
23
}
```
src/tools/greet.ts
```typescript
1
import { z } from "zod";
2
import { type InferSchema, type ToolMetadata } from "xmcp";
3
import { getSession } from "../lib/scalekit-auth";
4
5
export const schema = {
6
name: z.string().describe("The name to greet"),
7
};
8
9
export const metadata: ToolMetadata = {
10
name: "greet",
11
description: "Greet the user with their Scalekit identity",
12
};
13
14
export default function greet({
15
name,
16
}: InferSchema): string {
17
const session = getSession();
18
return `Hello, ${name}! Your user ID is ${session.userId}`;
19
}
```
8. ## Start the server [Section titled “Start the server”](#start-the-server) Terminal
```bash
npm run dev
```
You should see:
```plaintext
✔ MCP Server running on http://127.0.0.1:3001/mcp
[Scalekit] Resolved JWKS URI: https://.scalekit.com/keys
```
The JWKS log confirms the server successfully connected to Scalekit and can validate tokens. 9. ## Test with MCP Inspector [Section titled “Test with MCP Inspector”](#test-with-mcp-inspector) Verify the full flow using MCP Inspector. Terminal
```bash
npx @modelcontextprotocol/inspector@latest
```
In the Inspector UI: 1. Set transport to **Streamable HTTP**, URL to `http://localhost:3001/mcp`, connection to **Direct** 2. Get an access token using client credentials: Terminal
```bash
curl -s -X POST "$SCALEKIT_ENVIRONMENT_URL/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials\
&client_id=$SCALEKIT_CLIENT_ID\
&client_secret=$SCALEKIT_CLIENT_SECRET" | jq .access_token -r
```
3. Enable the **Authorization** custom header and set its value to `Bearer ` 4. Click **Connect** — you should see `whoami` and `greet` in the Tools tab You now have a working xmcp MCP server with Scalekit OAuth 2.1 authentication. Add more tools by creating files in `src/tools/`, and access the authenticated user from any tool via `getSession()`. For production deployment, build with `npm run build` and run the compiled output with `npm start`.