Fastmcp Auth
A FastMCP-based Model Context Protocol server providing timezone conversion tools with OAuth2 PKCE authentication support.
Ask AI about Fastmcp Auth
Powered by Claude Β· Grounded in docs
I know everything about Fastmcp Auth. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Authenticated FastMCP Server and Client
This project demonstrates a secure client-server setup using the FastMCP framework, with authentication handled by Microsoft Azure Entra ID. It includes:
- An MCP Server: A
FastMCPserver that exposes a simplereverse_tool. It's protected by Azure Entra ID, requiring a valid JWT Bearer token for access. - An MCP Client: A command-line client that authenticates against Azure Entra ID using a device flow, obtains a JWT token, and uses it to communicate with the secure MCP server.
- An Agent: An agent implementation that uses the FastMCP client to connect to the server and utilize its tools; Agent created with OpenAI Agents SDK which requires OpenAI API key in
.env
β οΈ Important: this does not follow the MCP authorization specification (e.g., with dynamic client registration etc...); this simply implements bearer auth as discussed here: https://gofastmcp.com/servers/auth/bearer; both the FastMCP server and client support this; this works with any auth service; this post uses Entra ID as an example
Diagram
graph TD
AAD[Azure Entra ID<br>OAuth 2.0/JWT Provider]
C[MCP Client<br>mcp_client.py]
DF[MSAL Device Flow]
TC[Token Cache<br>.token_cache.json]
S[FastMCP Server<br>mcp/main.py]
AUTH[BearerAuthProvider]
TOOL[reverse_tool]
C --> DF
DF --> AAD
AAD --> TC
TC --> C
C --> |MCP Tool Call with Bearer Token| AUTH
S --> AUTH --> TOOL
Features
- Secure MCP Server: Authentication middleware using
BearerAuthProviderto validate Azure Entra ID tokens. - Device Flow Authentication: User-friendly, browser-based authentication for the command-line client.
- Token Caching: The client caches the authentication token to avoid repeated logins.
- Asynchronous Communication: Built on
asynciofor efficient, non-blocking operations. - Progress Reporting: The server's tool reports progress back to the client during execution.
- Optional Authentication: The client can bypass authentication for testing against an unsecured server.
- Agent Implementation: An agent that utilizes the FastMCP client to connect to tools on the server.
Project Structure
.
βββ agent/ # Agent implementation using the FastMCP client
β βββ main.py # The agent application using FastMCP client
βββ api/ # Alternative FastAPI implementation
βββ mcp/
β βββ main.py # The FastMCP server application
βββ web/ # React-based web client
βββ mcp_client.py # The Python-based MCP client
βββ pyproject.toml # Project dependencies
βββ README.md # This file
Setup and Configuration
Prerequisites
- Python 3.8+
uvpackage manager (orpip)- An Azure account with permissions to create and manage App Registrations.
1. Clone the Repository
git clone <repository-url>
cd fastmcp-auth
2. Set up Azure Entra ID
You need to create two App Registrations in your Azure portal:
-
Server App Registration (API):
- Create a new App Registration for the MCP server.
- Go to Expose an API and set an Application ID URI. It will look like
api://<server-client-id>. - Add a scope named
executeand grant admin consent. - Note the Application (client) ID and the Directory (tenant) ID.
-
Client App Registration (Client):
- Create another App Registration for the client.
- Go to Authentication and enable "Allow public client flows".
- Go to API permissions, click Add a permission, select My APIs, and choose your server app.
- Select the
executepermission you created and grant admin consent. - Note the Application (client) ID.
3. Environment Configuration
The applications are configured using constants in the source code. For a production setup, it's recommended to use environment variables.
Server (mcp/main.py):
Update these values with your Azure App Registration details:
TENANT_ID: Your Azure Directory (tenant) ID.CLIENT_ID: The Application (client) ID of the server app registration.
Client (mcp_client.py):
Update these values with your Azure App Registration details:
TENANT_ID: Your Azure Directory (tenant) ID.CLIENT_ID: The Application (client) ID of the client app registration.API_SCOPE: The Application ID URI of the server app, appended with/.defaultor the specific scope name (e.g.,api://<server-client-id>/execute).
4. Install Dependencies
Use uv (or pip) and the pyproject.toml file to install the required Python packages.
uv pip install -r requirements.txt
(Note: If a requirements.txt does not exist, you may need to create one from pyproject.toml or install packages like fastmcp, msal, python-dotenv, click manually.)
Running the Applications
1. Start the MCP Server
Open a terminal and run the server:
python mcp/main.py
The server will start on http://0.0.0.0:8000. You will see log messages indicating that the authenticated server is running.
2. Run the MCP Client
Open a second terminal to run the client.
With Authentication (Default)
python mcp_client.py
Authentication Flow:
- The first time you run it, the client will initiate a device flow.
- You will be prompted to open a URL in your browser (e.g.,
https://microsoft.com/devicelogin) and enter a code. - After you authenticate and grant consent, the client will receive a JWT token.
- This token is cached in a file named
.token_cache.jsonin the project root. - The client then connects to the server, lists the available tools, and calls the
reverse_tool.
On subsequent runs, the client will silently use the cached token, and you won't need to log in again until it expires.
Without Authentication
If you want to test the client against a server that does not have authentication enabled, use the --no-auth flag:
python mcp_client.py --no-auth
This will skip the token acquisition process and send requests without an Authorization header.
3. Run the Agent
To run the agent, create a .env file in the agent folder with your Azure Entra ID configuration and then execute:
python agent/main.py
The agent will authenticate with Azure Entra ID, connect to the MCP server, and provide a rich UI for interacting with the tools.
How It Works
Server (mcp/main.py)
- Authentication Provider: It uses
fastmcp.server.auth.BearerAuthProviderto protect its endpoints. - Configuration: The provider is configured with the
jwks_uri,issuer,audience, and requiredscopesfor your Azure Entra ID tenant. The JWKS (JSON Web Key Set) URI is a standard endpoint where Azure publishes the public keys needed to verify its JWT signatures. - Token Validation: When the client sends a request with a
Bearertoken, theBearerAuthProviderautomatically:- Fetches the public key from the JWKS endpoint.
- Verifies the token's signature, issuer, and audience.
- Checks if the token has not expired.
- Ensures the token contains the required scopes (e.g., "execute").
- If any check fails, it returns a
401 Unauthorizedor403 Forbiddenerror.
- Tool: It defines a simple
reverse_toolthat reverses a string and reports its progress over 5 seconds.
Client (mcp_client.py)
- MSAL Library: It uses the
msal(Microsoft Authentication Library for Python) to handle the complexities of OAuth 2.0. - Public Client: It's configured as a
PublicClientApplication, which is suitable for desktop and mobile apps where the client secret cannot be securely stored. - Device Flow: For a command-line application, the device flow provides a secure way for users to sign in through their browser without the application having to handle credentials directly.
- Token Cache:
msalprovides a serializable token cache. The client script saves the cache to a local file (.token_cache.json) and loads it on startup. This provides a seamless single sign-on (SSO) experience after the first login. - API Calls: Once the
access_tokenis obtained, it's included in theAuthorizationheader of the HTTP requests sent to the MCP server by theStreamableHttpTransport.
Agent (agent/main.py)
- Agent Implementation: Uses the FastMCP client to connect to the server tools.
- Authentication: Similar to the client, it uses Azure Entra ID for authentication.
- Rich UI: Implements a rich console UI for interaction; when executing multiple tools simultaneously, progress indication might be hidden (UI is not the focus here so left it like that)
- Environment Configuration: Configures the agent using environment variables in a local
.envfile.
