mcp-https-OAuth-database-template: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a production-ready Python MCP (Model Context Protocol) server with OAuth 2.1 + PKCE authentication, designed for web deployment using HTTPS and Server-Sent Events (SSE). It uses the FastMCP framework and provides comprehensive OAuth endpoints for secure client integration.

Development Commands

Setup and Dependencies

# Install project dependencies
uv sync

# Install dev dependencies
uv sync --all-extras

Running the Server

Local development (Claude Desktop - stdio):

# Run in local mode with stdio transport (no OAuth, no HTTPS)
LOCAL_MODE=true uv run python server.py

# This mode is for Claude Desktop integration

Local development (Claude Code - HTTP):

# Run in HTTP mode locally for web clients
uv run python server.py

# Access at http://localhost:8899/sse

Production (HTTPS):

# Run with SSL enabled
SSL_ENABLED=true uv run python server.py

# Access at https://localhost:8443/sse

Code Quality Commands

# Format code
uv run black server.py oauth.py

# Type checking
uv run mypy server.py oauth.py

# Linting
uv run flake8 server.py oauth.py

# Run tests
uv run pytest

Architecture

Main components:

• server.py: Main application with HTTPS/SSE web server and comprehensive OAuth endpoints
  • Tools: add(a, b) and secret_word()
  • Resources: greeting://{name} dynamic resource
  • OAuth endpoints: /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource, /register, /authorize, /callback, /token
  • SSE transport for real-time communication with Claude Code
  • OAuth-aware authentication wrapper
• oauth.py: OAuth 2.1 + PKCE implementation with Google authentication
  • Dynamic Client Registration (RFC 7591)
  • OAuth Authorization Server Metadata (RFC 8414)
  • OAuth Protected Resource Metadata (RFC 8707)
  • PKCE support (RFC 7636)
  • JWT token generation and validation