Add comprehensive OAuth 2.0 authentication system#17
Merged
KeshavVarad merged 13 commits intomainfrom Nov 17, 2025
Merged
Conversation
Implements comprehensive OAuth 2.0 authentication system following TDD practices. Features: - PKCE (Proof Key for Code Exchange) support for secure OAuth flows - Base OAuthProvider class for extensible OAuth implementations - GitHub and Google OAuth providers with sensible defaults - Full async/await support throughout - Proper error handling with standardized exceptions - URL parameter encoding for OAuth redirect URLs Technical Details: - OAuthConfig: Configuration dataclass for OAuth providers - PKCEChallenge: Secure PKCE verifier/challenge generation - OAuthProvider: Abstract base class with: - Authorization URL generation with PKCE - Code-to-token exchange with state validation - Access token refresh flow - User info retrieval (provider-specific) - GitHubOAuthProvider: Ready-to-use GitHub OAuth - GoogleOAuthProvider: Ready-to-use Google OAuth with offline access Testing: - 29 comprehensive tests covering: - PKCE challenge generation and uniqueness - OAuth configuration - Authorization URL generation - Token exchange (success and error cases) - Token refresh (success and error cases) - User authentication - Provider-specific implementations - All 423 existing tests still pass (100% backward compatibility) Dependencies: - Added aiohttp>=3.8.0 as optional 'oauth' dependency - Updated pyproject.toml with oauth extras group Exports: - Updated nextmcp.auth.__init__ to export: - OAuthProvider, OAuthConfig, PKCEChallenge - GitHubOAuthProvider, GoogleOAuthProvider 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Implements comprehensive scope-based authorization system following TDD.
Features:
- Extended AuthContext with OAuth scope support
- has_scope() and add_scope() methods for scope management
- @requires_scope_async decorator for scope-based access control
- Scopes coexist with existing permissions and roles
- Full backward compatibility maintained
Technical Details:
- AuthContext.scopes: Set of OAuth scope strings
- AuthContext.has_scope(scope_name): Check if user has specific scope
- AuthContext.add_scope(scope): Add OAuth scope to context
- @requires_scope_async(*scopes): Decorator requiring any of the scopes
- OAuth providers now add scopes as both scopes AND permissions
Decorator Features:
- Must be used with @requires_auth_async
- Supports multiple scopes (user needs at least one)
- Works with both async and sync functions
- Preserves function metadata
- Can be stacked for AND logic
- Raises PermissionDeniedError with clear messaging
Backward Compatibility:
- OAuth scopes added as both scopes and permissions
- Existing @requires_permission_async still works
- All 423 existing tests pass
- AuthContext defaults to empty scopes set
- No breaking changes to existing APIs
Testing:
- 24 comprehensive scope tests covering:
- AuthContext scope methods
- @requires_scope_async decorator behavior
- OAuth integration with scopes
- Edge cases (empty strings, special chars)
- Coexistence with permissions/roles
- All 447 tests pass (100% success rate)
Exports:
- Updated nextmcp.auth.__init__ to export requires_scope_async
Use Cases:
@app.tool()
@requires_auth_async(provider=github_oauth)
@requires_scope_async("repo:read", "repo:write")
async def access_repos(auth: AuthContext):
# User must have repo:read OR repo:write scope
return {"repos": [...]}
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements comprehensive declarative security system following TDD practices.
Features:
- ScopeDefinition: Define OAuth scopes with provider mappings
- ToolPermission: Declarative tool permission requirements
- PermissionManifest: Centralized security policy definitions
- YAML/JSON manifest loading for configuration-driven security
- Runtime access control enforcement via check_tool_access()
- Support for roles, permissions, and OAuth scopes
Technical Details:
- ScopeDefinition dataclass:
- name: Scope identifier (e.g., "read:data")
- description: Human-readable description
- oauth_mapping: Provider-specific scope mappings (e.g., {"github": ["repo:read"]})
- ToolPermission dataclass:
- tool_name: Name of the tool to protect
- permissions: Required permissions (user needs ANY one - OR logic)
- scopes: Required OAuth scopes (user needs ANY one - OR logic)
- roles: Required roles (user needs ANY one - OR logic)
- description: Tool description
- dangerous: Flag for tools requiring extra confirmation
- PermissionManifest class:
- define_scope(): Programmatically define scopes
- define_tool_permission(): Programmatically define tool requirements
- load_from_dict(): Load manifest from dictionary
- load_from_yaml(): Load manifest from YAML file
- to_dict(): Export manifest to dictionary
- check_tool_access(tool_name, auth_context): Enforce access control
- Returns (allowed: bool, error_message: str | None)
- Unrestricted if tool not in manifest
- AND logic between requirement types (must have role AND permission AND scope if all specified)
- OR logic within requirement type (need ANY role from list)
Testing:
- 34 comprehensive tests covering:
- ScopeDefinition creation and serialization
- ToolPermission creation with all options
- PermissionManifest initialization and definition methods
- Dictionary and YAML loading/exporting
- Access control enforcement with roles, permissions, scopes
- Combined requirements (role + permission + scope)
- Edge cases (special characters, empty requirements, overwrites)
- Round-trip serialization
- All 481 total tests pass (100% backward compatibility)
Use Cases:
- Define security policies in YAML files
- Centralize permission management
- Support multi-tenant access control
- Map OAuth scopes to internal permissions
- Flag dangerous operations for extra confirmation
Example YAML Manifest:
```yaml
scopes:
- name: "read:data"
description: "Read access to data"
oauth_mapping:
github: ["repo:read"]
google: ["drive.readonly"]
tools:
query_database:
permissions: ["read:data"]
scopes: ["db.query.read"]
roles: ["viewer", "editor"]
description: "Query database"
dangerous: false
delete_all:
roles: ["admin"]
permissions: ["admin:all"]
dangerous: true
```
Exports:
- Updated nextmcp.auth.__init__ to export:
- PermissionManifest
- ScopeDefinition
- ToolPermission
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements specialized error types and @requires_manifest_async decorator.
Features:
- Standard error types for better error handling
- Manifest-middleware integration for declarative access control
- Comprehensive test coverage
Error Types:
- OAuthRequiredError: Raised when OAuth authentication is needed
- Attributes: provider, scopes, authorization_url, user_id
- Use when tool requires OAuth but user isn't authenticated via OAuth
- ScopeInsufficientError: Raised when user lacks required OAuth scopes
- Attributes: required_scopes, current_scopes, user_id
- Use when user is authenticated but missing necessary scopes
- ManifestViolationError: Raised when manifest access check fails
- Attributes: tool_name, required_roles, required_permissions, required_scopes, user_id, auth_context
- Use when user fails manifest-based access control
Manifest Middleware:
- @requires_manifest_async decorator:
- Enforces PermissionManifest at runtime
- Must be used with @requires_auth_async
- Auto-infers tool name from function name if not specified
- Raises ManifestViolationError with detailed context on denial
- Integration pattern:
```python
manifest = PermissionManifest()
manifest.define_tool_permission("admin_tool", roles=["admin"])
@requires_auth_async(provider=auth_provider)
@requires_manifest_async(manifest=manifest)
async def admin_tool(auth: AuthContext):
return "Admin action"
```
Testing:
- 19 tests for error types covering:
- Error creation and attributes
- Error inheritance and string conversion
- Raising and catching errors
- Common usage patterns
- 15 tests for manifest middleware covering:
- Unrestricted tools (not in manifest)
- Role-based access control
- Permission-based access control
- Scope-based access control
- Combined requirements (role AND permission AND scope)
- Error context propagation
- Tool name inference
- Integration patterns (wildcard permissions, shared manifests)
- All 515 total tests pass (100% backward compatibility)
Implementation Details:
- nextmcp/auth/errors.py: Three new exception classes
- nextmcp/auth/middleware.py: Added requires_manifest_async decorator (78 lines)
- Updated nextmcp/auth/__init__.py to export new errors and decorator
- Tests use proper APIKeyProvider format: valid_keys={"key": {"user_id": "..."}}
Use Cases:
- Provide clear, actionable error messages to clients
- Guide users through OAuth flows with authorization URLs
- Debug access control issues with full context
- Enforce manifest-based security declaratively
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements four production-ready example MCP servers demonstrating all auth features.
Examples:
1. GitHub OAuth Server (github_oauth_server.py)
- GitHub OAuth 2.0 with PKCE flow
- Repository access and management
- Scope-based access control
- OAuth authorization URL generation
- User profile retrieval
- Repository listing and creation
2. Google OAuth Server (google_oauth_server.py)
- Google OAuth 2.0 with offline access
- Refresh token support
- Google Drive file listing
- Gmail message listing
- Multiple OAuth scopes
- Token refresh demonstration
3. Permission Manifest Server (manifest_server.py)
- Declarative security with YAML/code
- @requires_manifest_async enforcement
- Role, permission, and scope requirements
- Dangerous operation flagging
- Multiple user roles (viewer, editor, admin, analyst)
- OR logic within types, AND logic between types
- Comprehensive demonstration of access patterns
4. Combined Auth Server (combined_auth_server.py)
- All auth features integrated
- Multiple providers (API Key, GitHub OAuth)
- RBAC with hierarchical roles
- Permission system
- OAuth scopes
- Manifest-based security
- Custom error handling
- Complete demonstration of:
- Public tools (no auth)
- Basic auth
- Role-based access
- Permission-based access
- Manifest enforcement
- Error type demonstrations
Features Demonstrated Across Examples:
- OAuth 2.0 Authorization Code Flow with PKCE
- Multiple OAuth providers (GitHub, Google)
- API Key authentication
- RBAC (Role-Based Access Control)
- Fine-grained permissions
- OAuth scope enforcement
- Permission manifests (YAML/code)
- Middleware decorators:
- @requires_auth_async
- @requires_role_async
- @requires_permission_async
- @requires_scope_async
- @requires_manifest_async
- Specialized error types:
- OAuthRequiredError
- ScopeInsufficientError
- ManifestViolationError
- Refresh token handling
- Declarative security policies
Each Example Includes:
- Complete working code
- Detailed documentation
- Setup instructions
- Usage examples
- Live demonstrations
- OAuth flow walkthroughs
Example Structure:
- examples/auth/github_oauth_server.py (374 lines)
- examples/auth/google_oauth_server.py (431 lines)
- examples/auth/manifest_server.py (409 lines)
- examples/auth/combined_auth_server.py (596 lines)
Total: 1,810 lines of production-ready example code
Usage:
Each example can be run standalone:
python examples/auth/github_oauth_server.py
python examples/auth/google_oauth_server.py
python examples/auth/manifest_server.py
python examples/auth/combined_auth_server.py
All examples tested and working successfully.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements comprehensive integration testing infrastructure for OAuth with real credentials. Integration Tests: - tests/test_oauth_integration.py (402 lines) - 10 integration tests (skip without credentials) - 1 setup instruction test (always runs) - Tests GitHub OAuth: URL generation, user info, authentication, error handling - Tests Google OAuth: URL generation, user info, authentication, token refresh, error handling - Proper skip conditions with helpful messages - Marked with @pytest.mark.integration for filtering Test Categories: 1. GitHub OAuth Integration (4 tests) - Authorization URL generation (with PKCE) - User info retrieval from GitHub API - Full authentication flow with access token - Invalid token error handling 2. Google OAuth Integration (6 tests) - Authorization URL generation (with offline access) - User info retrieval from Google API - Full authentication flow with access token - Token refresh flow (unique to Google) - Invalid access token error handling - Invalid refresh token error handling Running Tests: # Show what's needed (always runs) pytest tests/test_oauth_integration.py::test_show_setup_instructions -v # Run all integration tests (skips if no credentials) pytest tests/test_oauth_integration.py -v -m integration # Normal test run (skips integration tests gracefully) pytest # 516 passed, 10 skipped # With real credentials set export GITHUB_CLIENT_ID="..." GITHUB_CLIENT_SECRET="..." GITHUB_ACCESS_TOKEN="..." pytest tests/test_oauth_integration.py::TestGitHubOAuthIntegration -v Setup Documentation: - docs/OAUTH_TESTING_SETUP.md (494 lines) - Complete step-by-step setup for GitHub OAuth - Complete step-by-step setup for Google OAuth - Credential acquisition instructions - Token generation workflows (manual and automated) - Environment variable configuration - Troubleshooting guide - Security best practices - What each test verifies GitHub OAuth Setup: 1. Create OAuth App at https://github.com/settings/developers 2. Get Client ID and Client Secret 3. Use helper script or manual process to get access token 4. Set environment variables 5. Run tests Google OAuth Setup: 1. Create project at https://console.cloud.google.com 2. Enable APIs (Drive, Gmail, Google+) 3. Create OAuth 2.0 credentials 4. Configure consent screen and test users 5. Use helper script to get access + refresh tokens 6. Set environment variables 7. Run tests OAuth Token Helper: - examples/auth/oauth_token_helper.py (429 lines) - Interactive script to obtain OAuth tokens - Supports both GitHub and Google - Two modes: - Automatic: Starts local callback server, opens browser - Manual: Provides URLs, user pastes codes - Generates authorization URLs with PKCE - Exchanges codes for tokens - Tests tokens with real APIs - Displays export commands for environment variables - Formats .env file entries Usage: # Interactive mode python examples/auth/oauth_token_helper.py # Specify provider python examples/auth/oauth_token_helper.py --provider github python examples/auth/oauth_token_helper.py --provider google # Manual mode (no callback server) python examples/auth/oauth_token_helper.py --provider github --manual Features: - Automatic browser opening - Local callback server (http://localhost:8080/oauth/callback) - PKCE flow handling - Token validation with real APIs - Refresh token support (Google) - Clear step-by-step output - Copy-paste ready export commands Pytest Configuration: - Updated pyproject.toml with integration marker - Integration tests skip gracefully without credentials - Clear skip messages explain what's needed - Normal pytest runs automatically skip integration tests - Can explicitly run with: pytest -m integration - Can explicitly skip with: pytest -m "not integration" Environment Variables Required: GitHub: - GITHUB_CLIENT_ID (required for URL generation) - GITHUB_CLIENT_SECRET (required for URL generation) - GITHUB_ACCESS_TOKEN (required for authenticated tests) Google: - GOOGLE_CLIENT_ID (required for URL generation) - GOOGLE_CLIENT_SECRET (required for URL generation) - GOOGLE_ACCESS_TOKEN (required for authenticated tests) - GOOGLE_REFRESH_TOKEN (optional, for refresh tests) Testing Infrastructure: - Skip conditions with descriptive messages - Proper test isolation (each test independent) - Real API calls when credentials provided - Graceful degradation when credentials missing - Test output shows what was verified - Integration marker for filtering Example Test Output (with credentials): ✓ GitHub user info retrieved successfully User ID: 12345 Username: testuser Name: Test User Email: test@example.com Example Skip Output (without credentials): SKIPPED - GitHub OAuth credentials not configured. Set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET Files Added: - tests/test_oauth_integration.py (402 lines) - docs/OAUTH_TESTING_SETUP.md (494 lines) - examples/auth/oauth_token_helper.py (429 lines) Files Modified: - pyproject.toml (added integration marker) Total: 1,325 lines of integration testing infrastructure Benefits: 1. Verify OAuth works with real GitHub/Google APIs 2. Catch integration issues before production 3. Test error handling with real error responses 4. Validate token refresh flows 5. Document exact setup steps for users 6. Provide automated token acquisition 7. Enable CI/CD integration testing (with secrets) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Implements environment file infrastructure for secure credential management.
Files Added:
1. .env.example (template with placeholders)
- All required OAuth environment variables
- Comprehensive inline documentation
- Setup instructions in comments
- Loading examples (shell export, dotenv, etc.)
- Verification commands
- 3,380 bytes of documented configuration
2. scripts/setup_env.sh (environment setup script)
- Interactive setup wizard
- Creates .env from .env.example
- Provides step-by-step instructions
- Executable bash script
- Safe overwrite prompts
3. docs/ENV_SETUP.md (environment setup guide)
- Quick start guide
- Multiple loading methods
- Shell export, direnv, python-dotenv
- Security best practices
- Troubleshooting guide
- Environment variables reference table
- GitHub Actions integration example
Files Modified:
- .gitignore
- Added .env file patterns
- Ignores .env, .env.local, .env.test, .env.production
- Ignores *_credentials.json, *_token.json
- Explicitly allows .env.example (!.env.example)
Environment Variables Defined:
GitHub OAuth:
- GITHUB_CLIENT_ID
- GITHUB_CLIENT_SECRET
- GITHUB_ACCESS_TOKEN
Google OAuth:
- GOOGLE_CLIENT_ID
- GOOGLE_CLIENT_SECRET
- GOOGLE_ACCESS_TOKEN
- GOOGLE_REFRESH_TOKEN
Usage:
# Quick setup
bash scripts/setup_env.sh
# Or manual setup
cp .env.example .env
# Edit .env and fill in your values
nano .env
# Load variables
export $(cat .env | grep -v '^#' | xargs)
# Verify
echo $GITHUB_CLIENT_ID
echo $GITHUB_ACCESS_TOKEN
# Run tests
pytest tests/test_oauth_integration.py -v -m integration
Loading Methods:
1. Shell Export (Temporary):
export $(cat .env | grep -v '^#' | xargs)
2. Shell Config (Persistent):
# Add to ~/.bashrc or ~/.zshrc
if [ -f ~/path/to/nextmcp/.env ]; then
export $(cat ~/path/to/nextmcp/.env | grep -v '^#' | xargs)
fi
3. Direnv (Automatic):
brew install direnv
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
direnv allow .
4. Python dotenv:
from dotenv import load_dotenv
load_dotenv()
Security Features:
- .env files never committed (in .gitignore)
- Example file safe to commit (contains no secrets)
- Template uses placeholder values
- Clear warnings in comments
- Credential file patterns ignored
- Setup script checks for existing .env
Benefits:
1. Easy credential management
2. No hardcoding of secrets
3. Consistent across team members
4. Works with CI/CD (GitHub Actions secrets)
5. Multiple loading methods supported
6. Clear documentation and examples
Integration:
- Works with existing integration tests
- Compatible with pytest
- Supports GitHub Actions
- Python-dotenv compatible
- Shell-friendly format
Files Ignored by Git:
✓ .env (contains secrets)
✓ .env.local
✓ .env.test
✓ .env.production
✓ *_credentials.json
✓ *_token.json
✗ .env.example (template - safe to commit)
Verification:
# Check .env is ignored
git check-ignore .env
# Output: .env
# Check .env.example is tracked
git check-ignore .env.example
# Output: (empty - not ignored)
Documentation References:
- Quick Start: scripts/setup_env.sh --help
- Detailed Guide: docs/ENV_SETUP.md
- OAuth Setup: docs/OAUTH_TESTING_SETUP.md
- Integration Tests: tests/test_oauth_integration.py
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Finalizes the comprehensive OAuth 2.0 authentication system for NextMCP SDK. This commit completes the authentication extension by adding: Core Features: - Auth Metadata Protocol: Servers announce auth requirements to hosts - Request Enforcement Middleware: Runtime validation of tokens/scopes/permissions - Session Management: Persistent token storage with memory and file backends - Enhanced OAuth: Support for both JSON and form-encoded token responses New Modules: - nextmcp/protocol/auth_metadata.py: Auth metadata protocol definitions - nextmcp/session/session_store.py: Session storage implementations - nextmcp/auth/request_middleware.py: Request-level auth enforcement Error Handling: - AuthenticationError: General authentication failure - AuthorizationError: General authorization/access denial - Enhanced error context and messages OAuth Improvements: - Handle both JSON and form-encoded responses (GitHub vs Google) - Better error reporting for token exchange failures - Support for Content-Type detection in responses Documentation: - ARCHITECTURE.md: Deep dive into system design and components - HOST_INTEGRATION.md: Guide for host developers (Claude Desktop, etc.) - MIGRATION_GUIDE.md: How to add auth to existing servers Examples: - complete_oauth_server.py: Production-ready Google OAuth example - multi_provider_server.py: GitHub + Google OAuth with sessions - session_management_example.py: Advanced session workflows Test Coverage: - test_auth_metadata.py: Auth metadata protocol tests - test_request_middleware.py: Middleware enforcement tests - test_session_store.py: Session storage tests - Enhanced OAuth integration tests Integration: - Updated __init__.py exports for new components - Factory function create_auth_middleware() for easy setup - Seamless integration with existing FastMCP infrastructure Full Feature Summary (entire branch): - OAuth 2.0 with PKCE for public and confidential clients - GitHub and Google OAuth providers ready to use - Multi-provider support with unified interface - Role-Based Access Control (RBAC) - Fine-grained permissions and OAuth scope validation - Permission Manifest system (YAML/JSON declarative security) - Session persistence with automatic token refresh - Decorator-based access control - Comprehensive error types with context - 8 production-ready examples - Full test coverage (unit + integration) - 4 detailed documentation guides 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
The OAuth authentication system requires aiohttp for async HTTP requests in token exchange and refresh operations. Moving it from optional 'oauth' extras to main dependencies ensures it's always available when using the auth module. Fixes CI test failures: ModuleNotFoundError: No module named 'aiohttp' 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Reorder imports to satisfy ruff linting rules (I001). Moved request_middleware import after rbac for proper alphabetical order. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Fixes 6 linting issues: 1. Move PermissionManifest import to top using TYPE_CHECKING 2. Remove duplicate import from function scope 3. Use collections.abc.Callable instead of typing.Callable 4-6. Remove unnecessary 'r' mode argument from open() calls All changes follow modern Python best practices and pyupgrade recommendations. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Move TYPE_CHECKING block between standard library and local imports. Alphabetize typing imports (TYPE_CHECKING before Any). Follows isort conventions for import organization. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Reformatted 3 files to comply with Black style guide: - nextmcp/auth/manifest.py - nextmcp/auth/oauth.py - nextmcp/session/session_store.py All ruff linting checks now pass locally. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a complete, production-ready OAuth 2.0 authentication system to NextMCP SDK, enabling MCP servers to securely authenticate users with external providers.
Key Features
Architecture
The system is built on three layers:
nextmcp/protocol/) - Servers announce auth requirementsnextmcp/session/) - Persistent token storage with auto-refreshnextmcp/auth/request_middleware.py) - Runtime enforcementNew Modules
nextmcp/auth/oauth.py- OAuth 2.0 base implementation with PKCEnextmcp/auth/oauth_providers.py- GitHub and Google providersnextmcp/auth/manifest.py- Permission manifest systemnextmcp/auth/request_middleware.py- Request-level enforcementnextmcp/protocol/auth_metadata.py- Auth metadata protocolnextmcp/session/session_store.py- Session storage (memory/file)nextmcp/auth/errors.py- Enhanced error types with contextAuthorization Features
@requires_auth,@requires_scope,@requires_role, etc.Documentation
Examples (3,343 lines)
complete_oauth_server.py- Production-ready Google OAuth examplemulti_provider_server.py- GitHub + Google with session managementsession_management_example.py- Advanced session workflowsTest Coverage (1,846 lines)
Code Stats
Breaking Changes
None - this is a purely additive feature with backward compatibility.
Dependencies
aiohttp>=3.8.0for async HTTP requests (OAuth token exchange)Test Plan
Usage Example
🤖 Generated with Claude Code