Python MCP Weather Server with OAuth 2.1 Authentication

A production-ready Model Context Protocol (MCP) server built with FastAPI that provides weather information using the National Weather Service API. Features full MCP OAuth 2.1 compliance with PKCE, dynamic client registration, and Azure AD integration. Ready for deployment to Azure App Service with Azure Developer CLI (azd).

🌟 Features

MCP OAuth 2.1 Specification Compliant: Complete implementation of MCP Authorization Specification (2025-03-26)
PKCE Required: Secure authorization with Proof Key for Code Exchange (RFC 7636, S256 method)
Dynamic Client Registration: Automatic client registration per RFC 7591
Authorization Server Metadata: Discovery endpoint per RFC 8414
Third-Party Authorization: Uses Azure AD as authorization server
MCP Protocol Headers: Full support for MCP-Protocol-Version: 2025-03-26
JWT Token Management: Secure token-based authentication
Weather Tools:
- get_alerts: Get weather alerts for any US state
- get_forecast: Get detailed weather forecast for any location
Azure Ready: Pre-configured for Azure App Service deployment
Web Test Interface: Built-in OAuth 2.1 flow testing

🔐 MCP Authorization Implementation

This server implements the complete MCP Authorization Specification (2025-03-26):

OAuth 2.1 Endpoints

GET /.well-known/oauth-authorization-server - Authorization server metadata (RFC 8414)
POST /register - Dynamic client registration (RFC 7591)
GET /authorize - Authorization endpoint with PKCE (RFC 7636)
POST /token - Token endpoint for code exchange and refresh
GET /auth/azure/callback - Third-party authorization callback

MCP Protocol Features

✅ Protocol Version Headers: MCP-Protocol-Version: 2025-03-26
✅ PKCE Required: All clients must use S256 method
✅ Dynamic Registration: Automatic client onboarding
✅ JWT Authentication: Bearer token validation on MCP endpoints
✅ Proper Error Handling: 401/403/400 responses with details
✅ Azure AD Integration: Enterprise-grade authorization server

⚠️ Important: Complete OAuth setup required before use. See AUTH_SETUP.md for Azure AD configuration instructions.

💻 Local Development

Prerequisites

Python 3.8+
Azure account with completed OAuth setup (see AUTH_SETUP.md)

Setup & Run

Complete OAuth setup first: Follow the instructions in AUTH_SETUP.md to create your Azure App Registration.

Clone and install dependencies:

git clone <your-repo-url>
cd remote-mcp-webapp-python-auth-oauth
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows
# source venv/bin/activate   # macOS/Linux
pip install -r requirements.txt

Configure environment variables:

cp .env.example .env
# Edit .env with your Azure OAuth credentials from AUTH_SETUP.md

Start the development server:

.\start_server.ps1  # Windows
# or manually:
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Access the server:
- Server: http://localhost:8000/
- Health Check: http://localhost:8000/health
- OAuth 2.1 Test Interface: http://localhost:8000/mcp_oauth_test.html
- API Docs: http://localhost:8000/docs

🔌 Connect to the Local MCP Server

Authentication Required

Before connecting any MCP client, you must authenticate:

Get JWT Token: Visit http://localhost:8000/mcp_oauth_test.html
Complete OAuth Flow: Use the built-in OAuth 2.1 test interface
Copy JWT Token: Use the token in your MCP client configuration

Using MCP Inspector

In a new terminal window, install and run MCP Inspector:
```
npx @modelcontextprotocol/inspector
```
CTRL+click the URL displayed by the app (e.g. http://localhost:5173/#resources)
Configure authenticated connection:
- Set transport type to HTTP
- Set URL to: http://localhost:8000/
- Add Authorization header: Bearer <your-jwt-token>
💡 Getting your JWT token: Visit http://localhost:8000/mcp_oauth_test.html to complete the OAuth 2.1 flow and obtain your JWT token.
Test the connection: List Tools, click on a tool, and Run Tool

Configuration for MCP Clients

{
  "mcpServers": {
    "weather-mcp-server-local": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8000/",
        "headers": {
          "Authorization": "Bearer <your-jwt-token>"
        }
      },
      "name": "Weather MCP Server (Local with Auth)",
      "description": "Authenticated MCP Server with weather tools"
    }
  }
}
```   > 💡 **Replace `<your-jwt-token>`** with the actual JWT token obtained from the OAuth 2.1 flow at `/mcp_oauth_test.html`.

## 🚀 Quick Deploy to Azure

### Prerequisites

- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli)
- [Azure Developer CLI (azd)](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd)
- Active Azure subscription
- **Completed OAuth setup** (see [AUTH_SETUP.md](AUTH_SETUP.md))

### Deploy in 5 Commands

```bash
# 1. Login to Azure
azd auth login

# 2. Initialize the project  
azd init

# 3. Set OAuth environment variables (from your AUTH_SETUP.md)
azd env set AZURE_CLIENT_ID "your-client-id"
azd env set AZURE_TENANT_ID "your-tenant-id"
azd env set AZURE_CLIENT_SECRET "your-client-secret"
azd env set JWT_SECRET_KEY "your-secure-jwt-secret"

# 4. Deploy to Azure (first time to get the URL)
azd up

# 5. Update environment with deployed URL and redeploy
azd env set BASE_URL "https://app-web-[unique-id].azurewebsites.net"
azd env set AZURE_REDIRECT_URI "https://app-web-[unique-id].azurewebsites.net/auth/azure/callback"
azd env set ENVIRONMENT "production"
azd up

Post-Deployment Setup

⚠️ Critical: After deployment, you must update your Azure App Registration:

Note your deployed URL: https://app-web-[unique-id].azurewebsites.net/
Go to Azure Portal → Microsoft Entra ID → App registrations → Your App
Click Authentication → Add redirect URI: https://app-web-[unique-id].azurewebsites.net/auth/azure/callback
Click Save

💡 Note: The redirect URI must be /auth/azure/callback (not /auth/callback) for the MCP OAuth 2.1 flow to work correctly.

Test Your Deployment

After deployment, your authenticated MCP server will be available at:

OAuth 2.1 Test Interface: https://<your-app>.azurewebsites.net/mcp_oauth_test.html
Health Check: https://<your-app>.azurewebsites.net/health
MCP Capabilities: https://<your-app>.azurewebsites.net/mcp/capabilities
API Docs: https://<your-app>.azurewebsites.net/docs

🔌 Connect to the Remote MCP Server

Follow the same guidance as the local setup, but use your Azure App Service URL and ensure you have a valid JWT token from the deployed authentication endpoint.

Configuration for deployed server:

{
  "mcpServers": {
    "weather-mcp-server-azure": {
      "transport": {
        "type": "http", 
        "url": "https://<your-app>.azurewebsites.net/",
        "headers": {
          "Authorization": "Bearer <your-jwt-token>"
        }
      },
      "name": "Weather MCP Server (Azure with Auth)",
      "description": "Authenticated MCP Server hosted on Azure"
    }
  }
}

🧪 Testing

Interactive OAuth 2.1 Testing

Local: Visit http://localhost:8000/mcp_oauth_test.html
Azure: Visit https://<your-app>.azurewebsites.net/mcp_oauth_test.html

The test interface provides:

Complete OAuth 2.1 Flow: Dynamic client registration → Authorization → Token exchange
PKCE Validation: Test the full Proof Key for Code Exchange flow
MCP Endpoint Testing: Test authenticated weather tools
JWT Token Display: View and validate your authentication tokens
Client Callback Testing: Includes /client-callback endpoint for OAuth flow validation

OAuth Flow Architecture

The server implements a complete OAuth 2.1 flow:

Client Registration: Dynamic client registration with auto-generated credentials
Authorization: User redirected to Azure AD for authentication
Azure Callback: Server receives Azure auth code at /auth/azure/callback
Client Callback: Server redirects to client's callback (e.g., /client-callback) with authorization code
Token Exchange: Client exchanges authorization code for JWT access token

MCP Client Testing

Test with any MCP-compatible client using the authenticated endpoints and your JWT token.

🌦️ Data Source

This server uses the National Weather Service (NWS) API:

Real-time weather alerts and warnings
Detailed weather forecasts
Official US government weather data
No API key required
High reliability and accuracy

🔒 Security Features

✅ OAuth 2.1 Compliance: Full MCP Authorization Specification implementation
✅ PKCE Required: S256 method for all authorization flows
✅ Dynamic Client Registration: Secure automatic client onboarding
✅ Azure AD Integration: Enterprise-grade authorization server
✅ JWT Token Security: Configurable expiration and secure validation
✅ Protocol Version Enforcement: MCP-Protocol-Version header validation
✅ Request Logging: Full audit trail with user identification
✅ CORS Protection: Proper cross-origin resource sharing policies