Minimcp

Unlikely Features

The only feature that's not expected to be built into MiniMCP in the foreseeable future.

• 🚫 Session management

Using MiniMCP

The snippets below provide a quick overview of how to use MiniMCP. Check out the examples for more.

Installation

Python Requirement: Version 3.10 or higher.

MiniMCP is built on top of the official MCP Python SDK. Install it using pip or uv:

# Using pip
pip install minimcp

# Using uv (recommended)
uv add minimcp

Quick Start - Standalone ASGI App

MiniMCP can be easily deployed as an ASGI application.

# test.py

from minimcp import MiniMCP, HTTPTransport

# Create an MCP instance
mcp = MiniMCP(name="MathServer")

# Register tools and other primitives
@mcp.tool(description="Add two numbers")
def add(a: int, b: int) -> int:
    return a + b

# MCP server as ASGI Application
app = HTTPTransport(mcp).as_starlette("/mcp")

You can now start the server using uvicorn with four workers as follows.

uv run uvicorn test:app --workers 4

Basic Setup

The following example demonstrates simple registration and basic message processing using the handle function.

from minimcp import MiniMCP

mcp = MiniMCP(name="MathServer")

# Tool
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

# Prompt
@mcp.prompt()
def problem_solving(problem_description: str) -> str:
    """Prompt to systematically solve math problems."""
    return f"""You are a math problem solver. Solve the following problem step by step.
Problem: {problem_description}
"""

# Resource
@mcp.resource("math://constants/pi")
def pi_value() -> float:
    """Value of π (pi) to be used"""
    return 3.14

Internally, transport layers call handle() with the optional send callback and scope object:

# request_msg = '{"jsonrpc": "2.0", "id": "1", "method": "ping"}'
response_msg = await mcp.handle(request_msg, send_callback, scope)
# response_msg = '{"jsonrpc": "2.0", "id": "1", "result": {}}'

FastAPI Integration

This minimal example shows how to expose an MCP tool over HTTP using FastAPI.

from fastapi import FastAPI, Request
from minimcp import MiniMCP, HTTPTransport

# This can be an existing FastAPI/Starlette app (with authentication, middleware, etc.)
app = FastAPI()

# Create an MCP instance with optional typed scope
mcp = MiniMCP(name="MathServer")
transport = HTTPTransport(mcp)

# Register a simple tool
@mcp.tool(description="Add two numbers")
def add(a: int, b: int) -> int:
    return a + b

# Host MCP server
@app.post("/mcp")
async def handler(request: Request):
    # Pass auth, database connection and other metadata as part of scope (optional)
    scope = {"user_id": "123", "db": db_connection}
    return await transport.starlette_dispatch(request, scope)

Benchmark - MiniMCP vs FastMCP vs MCP Low-Level

Benchmarked against the standalone fastmcp package (v3.1.1, by Jeremiah Lowin) and the official MCP Python SDK mcp low-level server (v1.24.0).

MiniMCP is the fastest server in every one of the 36 test scenarios against both competitors:

• Wins all 36 test scenarios (3 transports × 3 workloads × 4 load levels) against both FastMCP and MCP Low-Level
• vs FastMCP: 28–64% faster response times; 37–126% higher throughput; 44–66% lower peak memory usage
• vs MCP Low-Level (STDIO): 8–52% faster response times; up to 54% higher throughput — MCP Low-Level ranks 2nd on STDIO
• vs MCP Low-Level (HTTP): 48–60% faster response times; 46–136% higher throughput — MCP Low-Level struggles at high concurrency, plateauing at ~180 RPS regardless of load
• Memory (HTTP): MiniMCP holds flat at ~22 MB under heavy load; FastMCP reaches ~63 MB, MCP Low-Level ~56 MB

For detailed results and architectural analysis, see the benchmark analysis report.

Test Environment

• Python Version: 3.10.12
• OS: Linux 6.8.0-106-generic
• Test Date: March 22, 2026
• Total Test Duration: ~9.3 hours

API Reference

This section provides an overview of the key classes, their functions, and the arguments they accept.

MiniMCP

from minimcp import MiniMCP is the key orchestrator for building an MCP server. It requires a server name as its only mandatory argument; all other arguments are optional. You can also specify the type of the scope object, which is passed through the system for static type checking.

MiniMCP provides:

• Tool, Prompt, and Resource managers — used to register message handlers.
• A Context manager — usable inside handlers.

The MiniMCP.handle() function processes incoming messages. It accepts a JSON-RPC 2.0 message string and two optional parameters — a send function and a scope object. MiniMCP controls how many handlers can run at the same time and how long each handler can remain idle. By default, idletimeout is set to 30 seconds and maxconcurrency to 100.

# Instantiation
mcp = MiniMCP[ScopeT](name, [version, instructions, idle_timeout, max_concurrency])

# Managers
mcp.tool
mcp.prompt
mcp.resource
mcp.context

# Message handling
response = await mcp.handle(message, [send, scope])

Primitive Managers/Decorators

MiniMCP supports three server primitives, each managed by its own manager class. These managers are available under MiniMCP as a callable instance that can be used as decorators for registering handler functions. They work similar to FastMCP's decorators.

The decorator accepts primitive details as argument (like name, description etc). If not provided, these details are automatically inferred from the handler function.

In addition to decorator usage, all three primitive managers also expose methods to add, list, remove, and invoke handlers programmatically.

Tool Manager

# As a decorator
@mcp.tool([name, title, description, annotations, meta])
def handler_func(...):...

# Methods for programmatic access
mcp.tool.add(handler_func, [name, title, description, annotations, meta])  # Register a tool
mcp.tool.remove(name)                                                      # Remove a tool by name
mcp.tool.list()                                                            # List all registered tools
mcp.tool.call(name, args)                                                  # Invoke a tool by name

Prompt Manager

# As a decorator
@mcp.prompt([name, title, description, meta])
def handler_func(...):...

# Methods for programmatic access
mcp.prompt.add(handler_func, [name, title, description, meta])
mcp.prompt.remove(name)
mcp.prompt.list()
mcp.prompt.get(name, args)

Resource Manager

# As a decorator
@mcp.resource(uri, [name, title, description, mime_type, annotations, meta])
def handler_func(...):...

# Methods for programmatic access
mcp.resource.add(handler_func, uri, [name, title, description, mime_type, annotations, meta])
mcp.resource.remove(name)
mcp.resource.list()                    # List all static resources
mcp.resource.list_templates()          # List all resource templates (URIs with parameters)
mcp.resource.read(uri)                 # Read a resource by URI, returns ReadResourceResult
mcp.resource.read_by_name(name, args)  # Read a resource by name with template args dict

Context Manager

The Context Manager provides access to request metadata (such as the message, scope, responder, and time_limiter) directly inside the handler function. It tracks the currently active handler context, which you can retrieve using mcp.context.get(). If called outside of a handler, this method raises a ContextError.

# Context structure
Context(Generic[ScopeT]):
    message: JSONRPCMessage           # The parsed request message
    time_limiter: TimeLimiter | None  # None

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cloudera](https://github.com/cloudera)
- **Source:** [cloudera/minimcp](https://github.com/cloudera/minimcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.