v0.6.0 - OAuth 2.0 Authentication System

NextMCP v0.6.0 - OAuth 2.0 Authentication System

A major feature release introducing comprehensive OAuth 2.0 support with GitHub and Google providers, session management, and the auth metadata protocol.

🚀 What's New

OAuth 2.0 Authentication

• Complete OAuth 2.0 implementation with PKCE support for secure authentication
• Ready-to-use providers for GitHub and Google with sensible defaults
• Extensible OAuth framework - easily create custom OAuth providers
• Full async/await support throughout the OAuth system

Session Management

• FileSessionStore - Persistent session storage that survives restarts
• MemorySessionStore - In-memory sessions for development
• Automatic token refresh - No manual token management required
• Session cleanup - Automatic expiration and cleanup of old sessions

Auth Metadata Protocol

• Server authentication announcements - Servers can declare auth requirements
• Host integration support - MCP hosts (Claude Desktop, Cursor) can query auth config
• Multiple auth flow types - Support for OAuth, API keys, JWT, and custom flows
• OAuth scope declarations - Declare required scopes for tools

Request Enforcement Middleware

• Runtime token validation - Validate tokens on every request
• OAuth scope verification - Ensure users have required scopes
• Permission and role checking - Integrate with existing RBAC system
• Automatic token refresh - Seamlessly refresh expired tokens

Permission Manifests

• Declarative permissions - Define permissions in YAML/JSON
• Tool-level access control - Specify permissions per tool
• Scope requirements - Integrate OAuth scopes with permissions
• RBAC integration - Works with NextMCP's RBAC system

📚 Documentation

We've added 2,717 lines of comprehensive documentation:

• ARCHITECTURE.md (726 lines) - Deep dive into OAuth system design and data flow
• OAUTH_TESTING_SETUP.md (436 lines) - Complete guide to setting up OAuth credentials
• MIGRATION_GUIDE.md (594 lines) - Step-by-step guide to adding auth to existing servers
• HOST_INTEGRATION.md (733 lines) - Guide for MCP host developers
• ENV_SETUP.md (228 lines) - Environment configuration best practices

💻 Examples

8 production-ready example servers (3,343 lines of code):

• complete_oauth_server.py - Production-ready Google OAuth with session management
• github_oauth_server.py - GitHub OAuth authentication example
• google_oauth_server.py - Google OAuth with API integrations
• multi_provider_server.py - Multiple OAuth providers in one server
• session_management_example.py - Advanced session workflows
• combined_auth_server.py - OAuth + RBAC + permissions
• manifest_server.py - Permission manifests with OAuth
• oauth_token_helper.py - Interactive OAuth testing tool

🧪 Testing

• 148 new tests for comprehensive OAuth coverage
• 11 integration tests with real GitHub and Google APIs
• 571 total tests - all passing
• 100% backward compatible - all existing tests still pass

🎯 Quick Start

Google OAuth

```python
from fastmcp import FastMCP
from nextmcp.auth import GoogleOAuthProvider, create_auth_middleware
from nextmcp.session import FileSessionStore
from nextmcp.protocol import AuthRequirement, AuthMetadata, AuthFlowType

mcp = FastMCP("My Secure Server")

Set up Google OAuth

google = GoogleOAuthProvider(
client_id=os.getenv("GOOGLE_CLIENT_ID"),
client_secret=os.getenv("GOOGLE_CLIENT_SECRET"),
scopes=["openid", "email", "profile"]
)

Create auth middleware with session storage

auth_middleware = create_auth_middleware(
provider=google,
requirement=AuthRequirement.REQUIRED,
session_store=FileSessionStore("./sessions")
)

mcp.use(auth_middleware)

Tools now require authentication

@mcp.tool()
async def get_user_data(ctx: Context) -> str:
return f"Hello {ctx.auth.username}!"
```

GitHub OAuth

```python
from nextmcp.auth import GitHubOAuthProvider

github = GitHubOAuthProvider(
client_id=os.getenv("GITHUB_CLIENT_ID"),
client_secret=os.getenv("GITHUB_CLIENT_SECRET"),
scopes=["user:email", "read:user"]
)

auth_middleware = create_auth_middleware(
provider=github,
requirement=AuthRequirement.REQUIRED,
session_store=FileSessionStore("./sessions")
)

mcp.use(auth_middleware)
```

📦 Installation

```bash
pip install nextmcp

Or with all dependencies

pip install nextmcp[all]
```

OAuth functionality is included in the base installation via the aiohttp dependency.

🔧 What Changed

• Updated README with comprehensive OAuth documentation
• Added OAuth 2.0 section with examples and usage patterns
• Updated installation instructions
• Updated feature comparison with FastMCP
• Bumped version to 0.6.0
• Added comprehensive CHANGELOG entry

📊 Code Statistics

• 5,628 lines added across 19 files
• 2,853 lines of core authentication framework
• 1,846 lines of comprehensive tests
• 3,343 lines of examples and documentation
• 7 new core modules
• 8 example servers
• 8 test suites

🔄 Breaking Changes

None - This release is 100% backward compatible with v0.5.0. All changes are additive.

🙏 Acknowledgments

This release represents a major milestone in NextMCP's authentication capabilities. Special thanks to all contributors and users who provided feedback.

---

Full Changelog: https://github.com/KeshavVarad/NextMCP/blob/main/CHANGELOG.md#060---2025-11-16

NextMCP v0.5.0 - Production Deployment System

NextMCP v0.5.0 - Production Deployment System

A major release adding comprehensive production deployment capabilities with health checks, graceful shutdown, and one-command deployment to multiple platforms.

🚀 What's New

Production Deployment System

Deploy your MCP servers to production with confidence:

# Initialize with Docker
cd my-mcp-project
mcp init --docker --with-database

# Deploy with one command
mcp deploy --platform docker

Health Check System

Built-in health checks for Kubernetes and cloud platforms:

from nextmcp.deployment import HealthCheck

health = HealthCheck()

# Add custom readiness checks
def check_database():
    return db.is_connected()

health.add_readiness_check("database", check_database)

Endpoints:

• GET /health - Liveness probe (is the app running?)
• GET /health/ready - Readiness probe (is the app ready for traffic?)

Graceful Shutdown

Clean resource cleanup on termination:

from nextmcp.deployment import GracefulShutdown

shutdown = GracefulShutdown(timeout=30.0)

def cleanup():
    db.close()
    cache.flush()

shutdown.add_cleanup_handler(cleanup)
shutdown.register()

Docker Templates

Production-optimized Docker configuration:

• Multi-stage builds (<100MB images)
• Non-root user (UID 1000)
• Built-in health checks
• Optional PostgreSQL/Redis integration

One-Command Deployment

# Docker
mcp deploy --platform docker

# Cloud platforms (Beta)
mcp deploy --platform railway
mcp deploy --platform render
mcp deploy --platform fly

📦 What's Included

New Modules

• nextmcp/deployment/health.py - Health check system
• nextmcp/deployment/lifecycle.py - Graceful shutdown
• nextmcp/deployment/templates.py - Template rendering
• nextmcp/templates/docker/ - Docker configuration templates

Enhanced CLI Commands

• mcp init --docker - Generate Docker deployment files
  • --with-database - Include PostgreSQL
  • --with-redis - Include Redis
  • --port - Custom port configuration
• mcp deploy - One-command deployment
  • --platform - Specify deployment target
  • --build/--no-build - Control build behavior

Examples

• examples/deployment_simple/ - Basic deployment with health checks
• examples/deployment_docker/ - Production-ready Docker deployment with database

Tests

• 21 health check tests
• 15 graceful shutdown tests
• 30 template rendering tests
• 363 total tests - All passing ✅

🧪 Platform Support

Platform	Status	CLI Required	Testing	Notes
Docker	✅ Full	docker, docker compose	✅ Automated CI	Fully tested, production-ready
Kubernetes	✅ Ready	kubectl	✅ Manifests validated	Health checks tested
Railway	🧪 Beta	railway	⚠️ Manual only	CLI integration, needs testing
Render	🧪 Beta	render	⚠️ Manual only	CLI integration, needs testing
Fly.io	🧪 Beta	flyctl	⚠️ Manual only	CLI integration, needs testing

Note on Beta Platforms: Railway, Render, and Fly.io deployments use their respective CLI tools. We test that commands are invoked correctly, but full platform integration requires manual verification. If you successfully deploy to these platforms (or encounter issues), please share your experience in GitHub Issues!

📊 Stats

• 66 new tests added
• 363 total tests (100% passing)
• 100% backward compatible - All existing tests pass
• 3,291 lines of deployment documentation
• Production-ready deployment patterns

🔧 Installation

pip install --upgrade nextmcp

📚 Documentation

• Deployment Guide
• Health Checks
• Graceful Shutdown
• Docker Deployment
• Cloud Platforms

🙏 Feedback Welcome

This is a major release with significant new functionality. We welcome:

• Bug reports and feature requests via GitHub Issues
• Community testing of Beta cloud platform deployments
• Documentation improvements via pull requests

📝 Full Changelog

See CHANGELOG.md for complete details.

---

Previous releases: v0.4.0 - Authentication System

v0.4.0: Authentication & Authorization System

🔐 Authentication & Authorization System

NextMCP v0.4.0 introduces a complete, production-ready authentication and authorization system with multiple providers, RBAC, and comprehensive middleware support.

✨ Highlights

• 3 Built-in Auth Providers: API Key, JWT, and Session-based authentication
• Complete RBAC System: Fine-grained permissions with wildcard support
• Middleware Decorators: Easy-to-use decorators for protecting tools
• 62 New Tests: Comprehensive test coverage for all auth features
• 3 Complete Examples: Working examples for each authentication method
• 100% Backward Compatible: All existing features continue to work

🚀 Key Features

Built-in Authentication Providers

Provider	Use Case	Dependencies
APIKeyProvider	Simple key-based auth	None
JWTProvider	Token-based, stateless	PyJWT
SessionProvider	Session-based, stateful	None

RBAC with Wildcard Permissions

# Define permissions with wildcards
rbac.define_permission("admin:*")  # All admin permissions
rbac.define_permission("read:posts")  # Specific permission

# Check permissions
if auth_context.has_permission("admin:users"):
    # Has admin:* or admin:users
    pass

Middleware Decorators

from nextmcp import NextMCP, requires_auth_async, requires_role_async

app = NextMCP("my-app")
provider = APIKeyProvider(valid_keys={...})

@app.tool()
@requires_auth_async(provider=provider)
@requires_role_async("admin")
async def admin_tool(auth: AuthContext, data: str) -> dict:
    return {"user": auth.username, "data": data}

📦 What's New

Core Components

• AuthContext: Authentication context with user info, roles, and permissions
• AuthProvider: Base class for custom authentication strategies
• Permission & Role: Fine-grained access control models
• RBAC: Complete role-based access control system

Auth Providers

• APIKeyProvider: Pre-configured or custom validation functions
• JWTProvider: HS256/RS256 algorithms, automatic expiration
• SessionProvider: In-memory sessions with auto-cleanup

Middleware

• @requires_auth / @requires_auth_async
• @requires_role / @requires_role_async
• @requires_permission / @requires_permission_async

📚 Examples

Three complete examples with READMEs:

1. API Key Auth (examples/auth_api_key/): Simple key-based authentication
2. JWT Auth (examples/auth_jwt/): Token-based authentication with login
3. RBAC (examples/auth_rbac/): Fine-grained permission control

🧪 Testing

• 26 Auth Provider Tests: APIKeyProvider, JWTProvider, SessionProvider
• 36 RBAC Tests: Permission, Role, AuthContext, RBAC system
• 297 Total Tests: All passing ✓

🛠️ Development Tools

• Pre-commit Hook: Automatic linting, formatting, and testing
• Installation Script: ./scripts/install-hooks.sh

📖 Documentation

• Comprehensive auth section in README (~400 lines)
• Full API documentation
• Security best practices
• Migration guide from previous versions

🔄 Backward Compatibility

This release is 100% backward compatible. All 235 existing tests pass without modification.

📝 Full Changelog

See CHANGELOG.md for complete details.

🙏 Contributors

Built with Claude Code

---

Installation: pip install nextmcp==0.4.0
PyPI: https://pypi.org/project/nextmcp/
Documentation: See README.md

v0.3.0 - Convention-based Project Structure

Convention-Based Project Structure with Auto-Discovery

This release introduces convention-based project structure with automatic discovery, bringing a Next.js-like developer experience to NextMCP.

🎯 Key Features

Single-Line Server Setup

from nextmcp import NextMCP

# That's it! Auto-discovers everything from directories
app = NextMCP.from_config()

if __name__ == "__main__":
    app.run()

Auto-Discovery Engine

• Automatically discovers tools from tools/ directory
• Automatically discovers prompts from prompts/ directory
• Automatically discovers resources from resources/ directory
• Supports nested directory structures
• Handles errors gracefully

Configuration-Based Setup

Create a nextmcp.config.yaml file:

name: my-server
version: 1.0.0
description: My awesome MCP server

auto_discover: true

discovery:
  tools: tools/
  prompts: prompts/
  resources: resources/

📦 What's New

Core Features

• ✅ Auto-Discovery Engine (nextmcp/discovery.py) - Scan directories and automatically register primitives
• ✅ NextMCP.from_config() - Single-line server setup with zero boilerplate
• ✅ Project Validation - validate_project_structure() function
• ✅ Configuration System - Support for nextmcp.config.yaml manifest

Example Project

• ✅ Blog Server (examples/blog_server/) - Complete convention-based example
  • 5 tools, 3 prompts, 4 resources
  • Single-line setup with NextMCP.from_config()
  • Before/after comparison in README

Testing

• ✅ 26 new comprehensive tests (235 total, all passing)
• Full coverage of auto-discovery, config loading, and integration

🔄 Backward Compatibility

100% Backward Compatible - All existing code continues to work without any changes. The new convention-based features are opt-in.

📊 Key Improvements

Aspect	Before	After
Setup	Manual registration	One-line from_config()
Organization	Single file	Convention-based directories
Structure	Unstructured	Organized (tools/, prompts/, resources/)
Discovery	Manual imports	Automatic from directories

📈 Statistics

• 32 files changed
• 1,823 additions
• 235 tests passing (26 new tests)
• Zero breaking changes

🚀 Getting Started

1. Create Project Structure

my-mcp-server/
├── nextmcp.config.yaml
├── tools/
│   └── my_tools.py
├── prompts/
│   └── my_prompts.py
└── resources/
    └── my_resources.py

2. Use Decorators in Files

# tools/my_tools.py
from nextmcp import tool

@tool()
def my_tool(param: str) -> str:
    return f"Result: {param}"

3. Single-Line Server Setup

# server.py
from nextmcp import NextMCP

app = NextMCP.from_config()

if __name__ == "__main__":
    app.run()

That's it! All tools, prompts, and resources are automatically discovered and registered.

📚 Documentation

• CHANGELOG
• Blog Server Example
• Main README

🙏 Credits

This release brings NextMCP's vision to life: making MCP server development as easy and enjoyable as Next.js made React development.

---

Full Changelog: v0.2.1...v0.3.0

v0.2.1 - Examples and Documentation

Added

Examples

• Knowledge Base Example (examples/knowledge_base/): Comprehensive example demonstrating all three MCP primitives working together
  • 3 Tools: search_knowledge, add_article, list_categories
  • 3 Prompts: research_prompt, summary_report_prompt, document_prompt
  • 4 Resources: stats, config, articles/{id}, category/{name}
  • Shows practical usage of tools, prompts, and resources in a real application
  • Includes argument/parameter completion examples
  • Demonstrates subscribable resources

Documentation

• Added comprehensive Prompts section to README

  • Basic prompts with examples
  • Prompts with argument completion
  • Dynamic completion functions
  • Async prompts
  • When to use prompts

• Added comprehensive Resources section to README

  • Direct resources with examples
  • Resource templates with parameters
  • Subscribable resources with notifications
  • Async resources
  • URI schemes and conventions
  • When to use resources

• Updated features list to highlight:

  • Full MCP specification support
  • Argument completion
  • Resource subscriptions
  • Cross-primitive middleware

Changed

• Enhanced feature descriptions to emphasize all three primitives

---

Full Changelog: https://github.com/KeshavVarad/NextMCP/blob/main/CHANGELOG.md

NextMCP v0.1.0 - Initial Release

Changelog

All notable changes to NextMCP will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

0.1.0 - 2025-11-03

Added

Core Features

• Initial release of NextMCP - Production-grade MCP server toolkit
• Decorator-based tool registration with @app.tool()
• Full async/await support for asynchronous tools
• Global and tool-specific middleware system
• Plugin architecture for extensibility

Middleware

• log_calls - Automatic logging of tool invocations
• error_handler - Structured error handling and responses
• require_auth - API key authentication
• rate_limit - Rate limiting per tool
• validate_inputs - Input validation middleware
• cache_results - Response caching
• timeout - Execution timeout enforcement
• Async versions of all middleware

Transport

• WebSocket transport for real-time bidirectional communication
• WebSocket client for connecting to remote MCP servers
• Message serialization and deserialization
• Tool invocation over WebSocket

Metrics & Monitoring

• Complete metrics collection system
• Counter, Gauge, Histogram, and Summary metric types
• Prometheus exporter for metrics
• JSON exporter for metrics
• Automatic tool invocation tracking
• Duration and error metrics
• Metrics middleware for transparent collection

Configuration

• Multi-source configuration management
• Support for .env files
• Support for YAML configuration files
• Environment variable overrides
• Hierarchical configuration with defaults

CLI Tools

• mcp init - Scaffold new projects from templates
• mcp run - Run MCP servers
• mcp docs - Generate documentation
• mcp version - Show version information
• Rich terminal output with syntax highlighting

Development Tools

• Comprehensive logging system with context support
• Tool metadata and documentation generation
• Plugin discovery and management
• Type hints and Pydantic integration support

Examples

• Weather Bot - Basic MCP server example
• Async Weather Bot - Asynchronous operations example
• WebSocket Chat - Real-time communication example
• Plugin Example - Custom plugin implementation
• Metrics Example - Monitoring and metrics collection

Testing

• 134 comprehensive tests covering all features
• Unit tests for core functionality
• Integration tests for middleware and plugins
• Async test support
• 100% of critical paths tested

Documentation

• Comprehensive README with examples
• API documentation in docstrings
• Example projects with detailed READMEs
• Configuration guides
• Middleware usage examples

Technical Details

• Python 3.8+ support
• Built on top of FastMCP
• Type-safe with full type hints
• Production-ready error handling
• Thread-safe metrics collection
• Modular architecture with optional dependencies

Package Structure

• Core package: nextmcp
• Optional dependencies for CLI, config, WebSocket, and schema validation
• Extensible plugin system
• Clean separation of concerns

Known Limitations

• Authentication system is basic (enhanced auth planned for v0.2.0)
• Metrics are in-memory only (persistent storage planned for future release)
• No built-in OAuth support yet (planned for v0.2.0)

---

Upcoming Features (Roadmap)

v0.2.0 (Planned)

• Advanced authentication system with secrets management
• OAuth 2.0 support
• Pre-built API clients (GitHub, Stripe, Slack)
• Persistent metrics storage
• Enhanced error handling
• More example integrations

v0.3.0 (Future)

• Distributed tracing
• Health check endpoints
• API versioning support
• GraphQL transport option
• Enhanced documentation site

---