New in version: 2.11.0
Token verification enables your FastMCP server to validate bearer tokens issued by external systems without participating in user authentication flows. Your server acts as a pure resource server, focusing on token validation and authorization decisions while delegating identity management to other systems in your infrastructure.
Token verification operates somewhat outside the formal MCP authentication flow, which expects OAuth-style discovery. It’s best suited for internal systems, microservices architectures, or when you have full control over token generation and distribution.
Understanding Token Verification
Token verification addresses scenarios where authentication responsibility is distributed across multiple systems. Your MCP server receives structured tokens containing identity and authorization information, validates their authenticity, and makes access control decisions based on their contents. This pattern emerges naturally in microservices architectures where a central authentication service issues tokens that multiple downstream services validate independently. It also works well when integrating MCP servers into existing systems that already have established token-based authentication mechanisms.The Token Verification Model
Token verification treats your MCP server as a resource server in OAuth terminology. The key insight is that token validation and token issuance are separate concerns that can be handled by different systems. Token Issuance: Another system (API gateway, authentication service, or identity provider) handles user authentication and creates signed tokens containing identity and permission information. Token Validation: Your MCP server receives these tokens, verifies their authenticity using cryptographic signatures, and extracts authorization information from their claims. Access Control: Based on token contents, your server determines what resources, tools, and prompts the client can access. This separation allows your MCP server to focus on its core functionality while leveraging existing authentication infrastructure. The token acts as a portable proof of identity that travels with each request.Token Security Considerations
Token-based authentication relies on cryptographic signatures to ensure token integrity. Your MCP server validates tokens using public keys corresponding to the private keys used for token creation. This asymmetric approach means your server never needs access to signing secrets. Token validation must address several security requirements: signature verification ensures tokens haven’t been tampered with, expiration checking prevents use of stale tokens, and audience validation ensures tokens intended for your server aren’t accepted by other systems. The challenge in MCP environments is that clients need to obtain valid tokens before making requests, but the MCP protocol doesn’t provide built-in discovery mechanisms for token endpoints. Clients must obtain tokens through separate channels or prior configuration.FastMCP Token Verification
FastMCP provides theTokenVerifier
class to handle token validation complexity while remaining flexible about token sources and validation strategies.
TokenVerifier Design
TokenVerifier
focuses exclusively on token validation without providing OAuth discovery metadata. This makes it ideal for internal systems where clients already know how to obtain tokens, or for microservices that trust tokens from known issuers.
The class validates token signatures, checks expiration timestamps, and extracts authorization information from token claims. It supports various token formats and validation strategies while maintaining a consistent interface for authorization decisions.
You can subclass TokenVerifier
to implement custom validation logic for specialized token formats or validation requirements. The base class handles common patterns while allowing extension for unique use cases.
JWT Token Verification
JSON Web Tokens (JWTs) represent the most common token format for modern applications. FastMCP’sJWTVerifier
validates JWTs using industry-standard cryptographic techniques and claim validation.
JWKS Endpoint Integration
JWKS endpoint integration provides the most flexible approach for production systems. The verifier automatically fetches public keys from a JSON Web Key Set endpoint, enabling automatic key rotation without server configuration changes.auth.yourcompany.com
. The verifier periodically fetches public keys from the JWKS endpoint and validates incoming tokens against those keys. Only tokens with the correct issuer and audience claims will be accepted.
The issuer
parameter ensures tokens come from your trusted authentication system, while audience
validation prevents tokens intended for other services from being accepted by your MCP server.
Symmetric Key Verification (HMAC)
Symmetric key verification uses a shared secret for both signing and validation, making it ideal for internal microservices and trusted environments where the same secret can be securely distributed to both token issuers and validators. This approach is commonly used in microservices architectures where services share a secret key, or when your authentication service and MCP server are both managed by the same organization. The HMAC algorithms (HS256, HS384, HS512) provide strong security when the shared secret is properly managed.- Simplicity: No key pair management or certificate distribution
- Performance: HMAC operations are typically faster than RSA
- Compatibility: Works well with existing microservice authentication patterns
The parameter is named
public_key
for backwards compatibility, but when using HMAC algorithms (HS256/384/512), it accepts the symmetric secret string.Security Considerations for Symmetric Keys:
- Use a strong, randomly generated secret (minimum 32 characters recommended)
- Never expose the secret in logs, error messages, or version control
- Implement secure key distribution and rotation mechanisms
- Consider using asymmetric keys (RSA/ECDSA) for external-facing APIs
Static Public Key Verification
Static public key verification works when you have a fixed RSA or ECDSA signing key and don’t need automatic key rotation. This approach is primarily useful for development environments or controlled deployments where JWKS endpoints aren’t available.Development and Testing
Development environments often need simpler token management without the complexity of full JWT infrastructure. FastMCP provides tools specifically designed for these scenarios.Static Token Verification
Static token verification enables rapid development by accepting predefined tokens with associated claims. This approach eliminates the need for token generation infrastructure during development and testing.Authorization: Bearer dev-alice-token
headers. The server will recognize the token and load the associated claims for authorization decisions. This approach enables immediate development without external dependencies.
Static token verification stores tokens as plain text and should never be used in production environments. It’s designed exclusively for development and testing scenarios.
Test Token Generation
Test token generation helps when you need to test JWT verification without setting up complete identity infrastructure. FastMCP includes utilities for generating test key pairs and signed tokens.Environment Configuration
New in version: 2.12.1
FastMCP supports both programmatic and environment-based configuration for token verification, enabling flexible deployment across different environments.
Environment-based configuration separates authentication settings from application code, following twelve-factor app principles and simplifying deployment pipelines.