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

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

2. 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
   

3. Configure environment variables:

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

4. Start the development server:

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

5. 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:

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

Using MCP Inspector

1. In a new terminal window, install and run MCP Inspector:

   npx @modelcontextprotocol/inspector
   

2. CTRL+click the URL displayed by the app (e.g. http://localhost:5173/#resources)

3. 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.

4. 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:

1. Note your deployed URL: https://app-web-[unique-id].azurewebsites.net/
2. Go to Azure Portal → Microsoft Entra ID → App registrations → Your App
3. Click Authentication → Add redirect URI: https://app-web-[unique-id].azurewebsites.net/auth/azure/callback
4. 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:

1. Complete OAuth 2.1 Flow: Dynamic client registration → Authorization → Token exchange
2. PKCE Validation: Test the full Proof Key for Code Exchange flow
3. MCP Endpoint Testing: Test authenticated weather tools
4. JWT Token Display: View and validate your authentication tokens
5. 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