tomevault-io Setup MCP Authentication
Configure authentication and authorization for an existing FastMCP server.
Usage
/setup-mcp-auth [auth-type]
Arguments
[auth-type]: Optional - Type of authentication (api-key, oauth, custom)
Execution Instructions for Claude Code
When this command is run:
- Locate the FastMCP server in the current project
- Determine authentication requirements
- Configure authentication based on selected type
- Add authorization rules to tools if needed
- Generate environment configuration
Interactive Session Flow
1. Locate Server
Looking for FastMCP server...
Found: src/server.ts
Is this the correct server file? (yes/no):
2. Authentication Type
What type of authentication do you want to configure?
1. API Key - Simple header-based authentication
2. Role-Based - API key with user roles
3. OAuth 2.0 - Google or custom OAuth provider
4. JWT Validation - Validate external JWT tokens
5. Custom - Implement your own authentication logic
Select (1-5):
3. API Key Configuration
For API Key (option 1):
API Key Configuration
Header name for API key [default: x-api-key]:
How should API keys be stored?
1. Environment variable
2. Database lookup
3. Static configuration
Select (1-3):
4. Role-Based Configuration
For Role-Based (option 2):
Role-Based Authentication
What roles do you need?
Example: admin,user,readonly
Roles (comma-separated):
How are roles determined?
1. From request header (e.g., x-role)
2. From API key lookup
3. From JWT claims
Select (1-3):
5. OAuth Configuration
For OAuth 2.0 (option 3):
OAuth Provider
Which OAuth provider?
1. Google
2. GitHub (custom setup)
3. Custom OAuth provider
Select (1-3):
For Google:
Google OAuth Setup
You'll need:
- Google Cloud Console project
- OAuth 2.0 credentials (Client ID and Secret)
- Authorized redirect URIs configured
Base URL for your server:
Example: https://your-server.com
Base URL:
OAuth scopes (comma-separated):
Default: openid,profile,email
Scopes [press Enter for default]:
6. JWT Validation
For JWT (option 4):
JWT Validation Setup
JWKS URI (JSON Web Key Set endpoint):
Example: https://auth.example.com/.well-known/jwks.json
JWKS URI:
Token issuer (iss claim):
Example: https://auth.example.com
Issuer:
Expected audience (aud claim):
Example: mcp://my-server
Audience:
7. Authorization Rules
Do you want to add authorization rules to existing tools?
1. Yes - Review and configure tool access
2. No - I'll add authorization manually
Select (1-2):
If yes:
Found tools:
1. tool-name-1
2. tool-name-2
3. tool-name-3
Which tools should be restricted? (comma-separated numbers, or 'all'):
For tool "tool-name-1", who can access?
1. Admin only
2. Specific roles (specify)
3. Authenticated users only
4. Custom logic (I'll implement)
Select:
Generated Code Examples
API Key Authentication
const server = new FastMCP({
name: "{{serverName}}",
version: "{{version}}",
authenticate: (request) => {
const apiKey = request.headers["{{headerName}}"];
if (!apiKey) {
throw new Response(null, {
status: 401,
statusText: "API key required",
});
}
// Validate API key
const validKey = process.env.API_KEY;
if (apiKey !== validKey) {
throw new Response(null, {
status: 401,
statusText: "Invalid API key",
});
}
return { authenticated: true };
},
});
Role-Based Authentication
// Define session type with roles
interface SessionData {
userId: string;
role: "admin" | "user" | "readonly";
}
const server = new FastMCP<SessionData>({
name: "{{serverName}}",
version: "{{version}}",
authenticate: async (request) => {
const apiKey = request.headers["x-api-key"];
if (!apiKey) {
throw new Response(null, {
status: 401,
statusText: "API key required",
});
}
// Look up user by API key
const user = await findUserByApiKey(apiKey);
if (!user) {
throw new Response(null, {
status: 401,
statusText: "Invalid API key",
});
}
return {
userId: user.id,
role: user.role,
};
},
});
// Admin-only tool
server.addTool({
name: "admin-dashboard",
description: "Admin-only dashboard access",
canAccess: (auth) => auth?.role === "admin",
execute: async (args, { session }) => {
return "Welcome admin " + session.userId;
},
});
// Tool for admin and user roles
server.addTool({
name: "edit-content",
description: "Edit content",
canAccess: (auth) => auth?.role === "admin" || auth?.role === "user",
execute: async (args) => {
return "Content edited";
},
});
// Read-only accessible to all authenticated users
server.addTool({
name: "view-content",
description: "View content",
execute: async (args) => {
return "Content here";
},
});
OAuth with Google Provider
import { FastMCP } from "fastmcp";
import { GoogleProvider } from "fastmcp/auth";
// Set up Google OAuth provider
const authProxy = new GoogleProvider({
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
baseUrl: "{{baseUrl}}",
scopes: [{{#each scopes}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}],
});
interface SessionData {
email: string;
name: string;
}
const server = new FastMCP<SessionData>({
name: "{{serverName}}",
version: "{{version}}",
oauth: {
enabled: true,
authorizationServer: authProxy.getAuthorizationServerMetadata(),
proxy: authProxy,
},
authenticate: async (request) => {
// OAuth tokens are validated by the proxy
// Extract user info from the validated session
const userInfo = await authProxy.getUserInfo(request);
return {
email: userInfo.email,
name: userInfo.name,
};
},
});
// Access user info in tools
server.addTool({
name: "whoami",
description: "Get current user info",
execute: async (args, { session }) => {
return "Logged in as: " + session.name + " (" + session.email + ")";
},
});
JWT Validation
import { FastMCP, DiscoveryDocumentCache } from "fastmcp";
import { buildGetJwks } from "get-jwks";
import fastJwt from "fast-jwt";
// Cache for OIDC discovery documents
const discoveryCache = new DiscoveryDocumentCache({
ttl: 3600000, // 1 hour
});
interface SessionData {
userId: string;
email?: string;
scope?: string;
}
const server = new FastMCP<SessionData>({
name: "{{serverName}}",
version: "{{version}}",
oauth: {
enabled: true,
authorizationServer: {
issuer: "{{issuer}}",
authorizationEndpoint: "{{issuer}}/oauth/authorize",
tokenEndpoint: "{{issuer}}/oauth/token",
jwksUri: "{{jwksUri}}",
responseTypesSupported: ["code"],
},
protectedResource: {
resource: "{{audience}}",
authorizationServers: ["{{issuer}}"],
},
},
authenticate: async (request) => {
const authHeader = request.headers.authorization;
if (!authHeader?.startsWith("Bearer ")) {
throw new Response(null, {
status: 401,
statusText: "Missing or invalid authorization header",
});
}
const token = authHeader.slice(7);
try {
// Get JWKS for token validation
const getJwks = buildGetJwks({
jwksUrl: "{{jwksUri}}",
cache: true,
rateLimit: true,
});
// Create JWT verifier
const verify = fastJwt.createVerifier({
key: async (token) => {
const { header } = fastJwt.decode(token, { complete: true });
const jwk = await getJwks.getJwk({
kid: header.kid,
alg: header.alg,
});
return jwk;
},
algorithms: ["RS256", "ES256"],
issuer: "{{issuer}}",
audience: "{{audience}}",
});
// Validate token
const payload = await verify(token);
return {
userId: payload.sub,
email: payload.email,
scope: payload.scope,
};
} catch (error) {
throw new Response(null, {
status: 401,
statusText: "Invalid token",
});
}
},
});
Custom Authentication
interface SessionData {
userId: string;
permissions: string[];
}
const server = new FastMCP<SessionData>({
name: "{{serverName}}",
version: "{{version}}",
authenticate: async (request) => {
// Implement your custom authentication logic
const token = request.headers["authorization"]?.replace("Bearer ", "");
if (!token) {
throw new Response(null, {
status: 401,
statusText: "Authentication required",
});
}
// Validate token and get user info
const user = await validateToken(token);
if (!user) {
throw new Response(null, {
status: 401,
statusText: "Invalid token",
});
}
return {
userId: user.id,
permissions: user.permissions,
};
},
});
// Permission-based access control
server.addTool({
name: "protected-action",
description: "Requires specific permission",
canAccess: (auth) => auth?.permissions.includes("action:execute"),
execute: async () => {
return "Action executed";
},
});
Passing Headers to Tools
import { IncomingHttpHeaders } from "http";
interface SessionData {
headers: IncomingHttpHeaders;
userId?: string;
}
const server = new FastMCP<SessionData>({
name: "{{serverName}}",
version: "{{version}}",
authenticate: async (request) => {
// Pass headers through for use in tools
return {
headers: request.headers,
userId: request.headers["x-user-id"] as string,
};
},
});
server.addTool({
name: "check-headers",
description: "Access request headers",
execute: async (args, { session }) => {
const userAgent = session.headers["user-agent"] || "Unknown";
return "User-Agent: " + userAgent;
},
});
Environment File Generation
Create .env.example:
# API Key Authentication
API_KEY=your-api-key-here
# OAuth (Google)
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
# JWT Validation
JWT_ISSUER=https://auth.example.com
JWT_AUDIENCE=mcp://my-server
JWKS_URI=https://auth.example.com/.well-known/jwks.json
Implementation Notes
- Find existing server: Locate and analyze FastMCP server configuration
- Backup current code: Create backup before modifying
- Update server config: Add authenticate function and oauth config
- Add type definitions: Create SessionData interface
- Update tools: Add canAccess to restricted tools
- Generate .env.example: Create environment template
- Add dependencies: Install required packages (get-jwks, fast-jwt for JWT)
- Summary: Show configuration and next steps
Converted and distributed by TomeVault — claim your Tome and manage your conversions.