MiniMCP - A minimal, stateless, and lightweight framework for building MCP servers #1761

sreenaths · 2025-12-10T08:33:28Z

MiniMCP is a new high-performance framework for building MCP servers with a focus on simplicity, statelessness, and embeddability. This PR introduces a complete implementation with core orchestration, managers, transports, comprehensive tests, benchmarks, examples, and documentation. Despite the breadth of features, the core implementation remains compact - just over 1,800 lines of code, excluding docstrings.

Motivation and Context

While the existing FastMCP and low-level server implementations work well for many use cases, there's a need for a more lightweight, stateless approach that:

Enables horizontal scaling - Stateless design allows running multiple workers and deploying to serverless environments.
Simplifies web framework integration - Easily embed MCP servers into existing FastAPI, Django, or other Python web applications.
Provides flexibility - Bidirectional communication could be optional; a simple HTTP request/response works for many use cases.
Improves performance - Benchmarks show 20-67% faster response times and 17-28% lower memory usage compared to FastMCP.
Maintains security control - When adding MCP to an existing application, rely on its current auth mechanisms rather than enforcing new ones.

MiniMCP orchestration layer exposes a single asynchronous handle() function that processes JSON-RPC 2.0 messages, making it transport-agnostic and easy to integrate anywhere.

Benchmarks

Comprehensive benchmark suite comparing MiniMCP vs FastMCP
Tests across all transports with multiple load profiles (sequential, light, medium, heavy)
Results show significant performance improvements:
- 20-67% faster response times
- 10-173% higher throughput
- 17-28% lower memory usage

How Has This Been Tested?

Unit Tests

Comprehensive unit test coverage for all components:
- MiniMCP core orchestrator
- Tool, Resource, and Prompt managers
- All three transports (stdio, HTTP, streamable HTTP)
- Limiter, Responder, and Context manager
- JSON-RPC utilities and message handling
- MCPFunc wrapper and validation

Integration Tests

End-to-end tests for all three transports
Tests use real MCP clients to verify protocol compliance
Process management and concurrent request handling verified

Manual Testing

Math MCP server tested with Claude Desktop (stdio transport)
Web framework examples verified with FastAPI and Django
Issue tracker example tested with scope-based authentication
All transports tested with real client connections
Progress reporting and bidirectional communication verified

Examples

Math MCP server with all transport implementations
Web framework integration examples (FastAPI, Django)
Issue tracker demonstrating scope-based authentication

Breaking Changes

None. This is a new addition to the SDK and does not affect existing FastMCP or low-level server implementations.

Types of changes

New feature (non-breaking change which adds functionality)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Architecture

MiniMCP consists of several key components:

Core Orchestrator (MiniMCP) - Message lifecycle management, validation, dispatch, and error handling
Managers - ToolManager, PromptManager, ResourceManager for primitive registration and execution
Context Management - Thread-safe context isolation using contextvars with typed scope support
Transports - StdioTransport, HTTPTransport, StreamableHTTPTransport (with SSE)
Concurrency Control - Limiter with configurable idle timeout and max concurrency
Bidirectional Communication - Responder for server-to-client notifications

Key Design Decisions

Stateless by design - No session management; each request is self-contained
Transport agnostic - Core handles JSON-RPC strings; transport layer is fully decoupled
Scope object - Generic typed scope for passing auth, user info, DB handles, etc.
Optional bidirectional - HTTP transport works without SSE; StreamableHTTPTransport adds it on demand
Minimal dependencies - Only depends on the official MCP SDK core

Documentation

Complete README (591 lines) with architecture, API reference, examples, and troubleshooting
Testing guide (800 lines) covering unit, integration, and benchmark testing
Benchmark analysis report with detailed performance comparison
Examples demonstrating various use cases and integration patterns

Future Work

Potential additions (not in this PR):

Additional web framework integrations (Flask, Django native support)
Client primitives (sampling, logging)
Resumable Streamable HTTP with GET support
Fine-grained access control (FGAC)
Pagination support

- Define external errors (MiniMCPError and subclasses) - Define internal errors (InternalMCPError and subclasses) - Define special tool errors (SpecialToolError hierarchy) - Define message handling types (Message, NoMessage, Send)

- Implement message builders for responses, notifications, and errors - Add utility functions for request ID extraction and validation - Add JSONRPCEnvelope helper for efficient message parsing - Add comprehensive unit test suite for the above

- Add MCPFunc class for validating and executing MCP handler functions - Support automatic schema generation from function signatures - Add argument validation and async/sync execution support - Add comprehensive unit test suite

- Implement ToolManager class for managing MCP tool handlers - Add tool registration via decorator (@mcp.tool()) or programmatically - Support tool listing, calling, and removal operations - Add automatic schema inference from function signatures - Add error handling with special tool exceptions - Add comprehensive unit test suite

- Implement ResourceManager class for managing MCP resource handlers - Add support for static resources and resource templates (parameterized URIs) - Add resource registration via decorator (@mcp.resource(uri)) or programmatically - Support resource listing, reading by URI/name, and removal operations - Add URI pattern matching and template parameter validation - Add comprehensive unit test suite

…ution - Implement PromptManager class for managing MCP prompt handlers - Add prompt registration via decorator (@mcp.prompt()) or programmatically - Support prompt listing, getting, and removal operations - Add automatic argument inference from function signatures - Add support for multiple content types and annotations - Add comprehensive unit test suite

- Implement Limiter class for enforcing concurrency and idle timeout limits - Add TimeLimiter for resettable idle timeout management - Support configurable max_concurrency and idle_timeout settings - Add comprehensive unit test suite

- Implement Responder class for sending notifications from handlers to clients - Add report_progress() method for progress updates during long-running operations - Add send_notification() method for general server notifications - Support automatic idle timeout reset when sending notifications - Add comprehensive unit test suite

- Implement ContextManager for tracking active handler contexts - Add Context dataclass for holding request metadata (message, time_limiter, scope, responder) - Support thread-safe and async-safe context isolation using contextvars - Add helper methods (get_scope, get_responder) for common access patterns - Add comprehensive unit test suite

- Implement MiniMCP class as main entry point for building MCP servers - Integrate ToolManager, PromptManager, ResourceManager, and ContextManager - Add message processing pipeline (parsing, validation, dispatch, error handling) - Add concurrency control with configurable idle timeout and max concurrency - Support protocol handshake with initialize request/response handling - Add comprehensive unit test suite - Added RESOURCE_NOT_FOUND in mcp.types

- Implement StdioTransport per MCP stdio specification - Add message reading from stdin and writing to stdout - Support newline-delimited JSON-RPC message protocol - Add message validation (no embedded newlines per spec) - Support concurrent message handling with task groups - Add comprehensive unit test suite

…ansport) - Implement BaseHTTPTransport as abstract base for HTTP transports - Add HTTPTransport for standard HTTP POST request/response - Add dispatch() method for handling HTTP requests to MiniMCP - Add protocol version validation via MCP-Protocol-Version header - Add request validation (method, headers, media type) - Add Starlette support - Add comprehensive unit test suites

…TP communication - Implement StreamableHTTPTransport extending BaseHTTPTransport - Add dispatch() method with streaming response handling - Add SSE (Server-Sent Events) support for server-to-client streaming - Add StreamManager for lifecycle management of memory object streams - Support bidirectional communication (POST requests + SSE responses) - Add graceful stream cleanup with configurable drain delay - Add Starlette support - Add comprehensive unit test suite

- Export MiniMCP, transports, and core types - Export orchestration classes and exceptions - Define __all__ for explicit public API

…transports - Add integration test suite for StdioTransport - Add integration test suite for HTTPTransport - Add integration test suite for StreamableHTTPTransport - Add test helpers (client session, HTTP utilities, process management) - Add math_mcp example server for integration testing - Add server fixtures and conftest configuration - Add psutil dependency for process management in tests

- Add math_mcp.py with tools, prompts, and resources - Add server implementations for all three transports - Demonstrate MiniMCP features with mathematical operations

- Add issue tracker MCP with scope-based auth - Add FastAPI integration example - Add Django WSGI integration example

- Add benchmarking framework and infrastructure - Add benchmarks for all three transports (stdio, HTTP, streamable HTTP) - Add analysis tools and comprehensive performance report - Include benchmark results for sync and async tool calls

- Add README.md with complete MiniMCP guide and API reference - Add TESTING.md with testing documentation - Document architecture, examples, and troubleshooting

- Add tests for error scenarios across all managers and transports - Add edge case coverage for MiniMCP core orchestrator - Add validation and error handling tests - Clean up test imports

sreenaths · 2025-12-10T10:20:34Z

Checks are failing due to coverage issues. I’m working on it.

maxisbey · 2025-12-10T15:04:12Z

Thanks for putting this together, clearly took quite a bit of work!

Unfortunately we're going to close this PR as it's out of scope for the SDK. We currently already maintain two server layers/implementations, lowlevel and FastMCP. Adding a third would be a lot of maintenance burden. For these sorts of massive wide scale additions/changes we first would need this to be discussed, designed, and planned along with the maintainers of the Python SDK. We're soon going to be adding explicit wording around this to the CONTRIBUTING.md file.

If you'd like to continue developing this, I'd recommend publishing this as a standalone package, similar to how FastMCP 2 split off to build their own package.

sreenaths · 2025-12-10T17:19:39Z

Thank you for the review, @maxisbey.

sreenaths · 2025-12-15T20:35:26Z

Linking issue #1371 for context.
It was opened earlier to discuss adding MiniMCP to the official Python SDK.

sreenaths mentioned this pull request Dec 10, 2025

Can MiniMCP (a lightweight stateless MCP server framework) be part of the SDK? #1371

Closed

sreenaths added 19 commits December 10, 2025 00:46

[minimcp] Add exception hierarchy and message types

ff63eaa

- Define external errors (MiniMCPError and subclasses) - Define internal errors (InternalMCPError and subclasses) - Define special tool errors (SpecialToolError hierarchy) - Define message handling types (Message, NoMessage, Send)

[minimcp] Add JSON-RPC message utilities

24bf23c

- Implement message builders for responses, notifications, and errors - Add utility functions for request ID extraction and validation - Add JSONRPCEnvelope helper for efficient message parsing - Add comprehensive unit test suite for the above

[minimcp] Public API exports

0f9ffd2

- Export MiniMCP, transports, and core types - Export orchestration classes and exceptions - Define __all__ for explicit public API

[minimcp][examples] Add math_mcp example server

da9dde5

- Add math_mcp.py with tools, prompts, and resources - Add server implementations for all three transports - Demonstrate MiniMCP features with mathematical operations

[minimcp][examples] Add web framework examples with authentication

872d6f3

- Add issue tracker MCP with scope-based auth - Add FastAPI integration example - Add Django WSGI integration example

[minimcp] Add comprehensive documentation

36c3166

- Add README.md with complete MiniMCP guide and API reference - Add TESTING.md with testing documentation - Document architecture, examples, and troubleshooting

sreenaths force-pushed the minimcp-prime branch from a3900c2 to 36c3166 Compare December 10, 2025 08:46

[minimcp] Improve test coverage for edge cases and error handling

56fe6a3

- Add tests for error scenarios across all managers and transports - Add edge case coverage for MiniMCP core orchestrator - Add validation and error handling tests - Clean up test imports

maxisbey closed this Dec 10, 2025

sreenaths mentioned this pull request Dec 11, 2025

Proposal: Split Server class into MCPCore (handler management) (tentative name) and Server (runtime) #1779

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

MiniMCP - A minimal, stateless, and lightweight framework for building MCP servers #1761

MiniMCP - A minimal, stateless, and lightweight framework for building MCP servers #1761

Uh oh!

sreenaths commented Dec 10, 2025 •

edited

Loading

Uh oh!

sreenaths commented Dec 10, 2025 •

edited

Loading

Uh oh!

maxisbey commented Dec 10, 2025

Uh oh!

sreenaths commented Dec 10, 2025

Uh oh!

sreenaths commented Dec 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MiniMCP - A minimal, stateless, and lightweight framework for building MCP servers #1761

MiniMCP - A minimal, stateless, and lightweight framework for building MCP servers #1761

Uh oh!

Conversation

sreenaths commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

Benchmarks

How Has This Been Tested?

Unit Tests

Integration Tests

Manual Testing

Examples

Breaking Changes

Types of changes

Checklist

Additional context

Architecture

Key Design Decisions

Documentation

Future Work

Uh oh!

sreenaths commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maxisbey commented Dec 10, 2025

Uh oh!

sreenaths commented Dec 10, 2025

Uh oh!

sreenaths commented Dec 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sreenaths commented Dec 10, 2025 •

edited

Loading

sreenaths commented Dec 10, 2025 •

edited

Loading