# Minimcp

> A minimal, stateless, and lightweight framework for building MCP servers.

- **Type:** MCP server
- **Install:** `agentstack add mcp-cloudera-minimcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cloudera](https://agentstack.voostack.com/s/cloudera)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [cloudera](https://github.com/cloudera)
- **Source:** https://github.com/cloudera/minimcp

## Install

```sh
agentstack add mcp-cloudera-minimcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

### 

[](https://pypi.org/project/minimcp/)
[](https://deepwiki.com/cloudera/minimcp)

A **minimal, stateless, and lightweight** framework for building MCP servers.

_Simple async function interface_ ⭐ _Bidirectional messaging is optional_ ⭐ _Remote & local servers_ ⭐ _Built-in transports - stdio, HTTP, and 'Smart' Streamable HTTP_ ⭐ _Embeddable into any Python web application_ ⭐ _Based on official MCP Python specification._

## Table of Contents

- [What is MCP?](https://github.com/cloudera/minimcp#what-is-mcp)
- [Why MiniMCP?](https://github.com/cloudera/minimcp#why-minimcp)
  - [When to Use MiniMCP](https://github.com/cloudera/minimcp#when-to-use-minimcp)
  - [Currently Supported Features](https://github.com/cloudera/minimcp#currently-supported-features)
  - [Planned Features](https://github.com/cloudera/minimcp#planned-features)
  - [Unlikely Features](https://github.com/cloudera/minimcp#unlikely-features)
- [Using MiniMCP](https://github.com/cloudera/minimcp#using-minimcp)
  - [Installation](https://github.com/cloudera/minimcp#installation)
  - [Quick Start - Standalone ASGI App](https://github.com/cloudera/minimcp#quick-start---standalone-asgi-app)
  - [Basic Setup](https://github.com/cloudera/minimcp#basic-setup)
  - [FastAPI Integration](https://github.com/cloudera/minimcp#fastapi-integration)
- [Benchmark - MiniMCP vs FastMCP vs MCP Low-Level](https://github.com/cloudera/minimcp#benchmark---minimcp-vs-fastmcp-vs-mcp-low-level)
- [API Reference](https://github.com/cloudera/minimcp#api-reference)
  - [MiniMCP](https://github.com/cloudera/minimcp#minimcp)
  - [Primitive Managers/Decorators](https://github.com/cloudera/minimcp#primitive-managersdecorators)
    - [Tool Manager](https://github.com/cloudera/minimcp#tool-manager)
    - [Prompt Manager](https://github.com/cloudera/minimcp#prompt-manager)
    - [Resource Manager](https://github.com/cloudera/minimcp#resource-manager)
  - [Context Manager](https://github.com/cloudera/minimcp#context-manager)
- [Transports](https://github.com/cloudera/minimcp#transports)
  - [Stdio Transport](https://github.com/cloudera/minimcp#stdio-transport)
  - [HTTP Transport](https://github.com/cloudera/minimcp#http-transport)
  - [Smart Streamable HTTP Transport](https://github.com/cloudera/minimcp#smart-streamable-http-transport)
- [Testing](https://github.com/cloudera/minimcp#testing)
- [Error Handling](https://github.com/cloudera/minimcp#error-handling)
  - [Protocol-Level Errors](https://github.com/cloudera/minimcp#protocol-level-errors)
  - [Transport Error Handling](https://github.com/cloudera/minimcp#transport-error-handling)
- [Examples](https://github.com/cloudera/minimcp#examples)
  - [1. Math MCP server](https://github.com/cloudera/minimcp#1-math-mcp-server)
    - [Claude Desktop](https://github.com/cloudera/minimcp#claude-desktop)
  - [2. Integrating With Web Frameworks](https://github.com/cloudera/minimcp#2-integrating-with-web-frameworks)
- [FAQ](https://github.com/cloudera/minimcp#faq)
- [Documentation](https://github.com/cloudera/minimcp#documentation)
- [Contributing](https://github.com/cloudera/minimcp#contributing)
- [License](https://github.com/cloudera/minimcp#license)

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a powerful, standardized way for AI applications to connect with external data sources and tools. It follows a client–server architecture, where communication happens through well-defined MCP messages in the JSON-RPC 2.0 format. The key advantage of MCP is its interoperability: once a server supports MCP, any MCP-compatible AI client can connect to it without custom integration code. The official MCP Python SDK provides a low-level implementation of the protocol, while [FastMCP](https://github.com/jlowin/fastmcp) offers a higher-level, Pythonic interface.

## Why MiniMCP?

MiniMCP rethinks the MCP server from the ground up, keeping the core functionality lightweight and independent of transport layer, bidirectional communication, session management, and auth mechanisms. Additionally, instead of a stream-based interface, MiniMCP exposes a simple asynchronous handle function that takes a JSON-RPC 2.0 message string as input and returns a JSON-RPC 2.0 message string as output.

- **Stateless:** Scalability, simplicity, and reliability are crucial for remote MCP servers. MiniMCP provides all of those by being stateless at its core — each request is self-contained, and the server maintains no persistent session state.
  - This design makes it robust and easy to scale horizontally.
  - This also makes it a perfect fit for **serverless architectures**, where ephemeral execution environments are the norm.
  - Want to start your MCP server using uvicorn with multiple workers? No problem.
- **Bidirectional is optional:** Many use cases work perfectly with a simple request–response channel without needing bidirectional communication. MiniMCP was built with this in mind and provides a simple HTTP transport while adhering to the specification.
- **Embeddable:** Already have an application built with FastAPI (or another framework)? You can embed a MiniMCP server under a single endpoint, or multiple servers under multiple endpoints — _As a cherry on the cake, you can use your existing dependency injection system._
- **Scope and Context:** MiniMCP provides a type-checked scope object that travels with each message. This allows you to pass extra details such as authentication, user info, session data, or database handles. Inside the handler, the scope is available as part of the context — _So you’re free to use your preferred session or user management mechanisms._
- **Security:** MiniMCP encourages you to use your existing battle-tested security mechanism instead of enforcing one - _In other words, a MiniMCP server built with FastAPI can be as secure as any FastAPI application!_
- **Stream on Demand:** MiniMCP comes with a smart streamable HTTP transport. It opens an event stream only when the server needs to push notifications to the client.
- **Separation of Concerns:** The transport layer is fully decoupled from message handling. This makes it easy to adapt MiniMCP to different environments and transport protocols without rewriting your core business logic.
- **Minimal Dependencies:** MiniMCP keeps its footprint small, depending only on the official MCP SDK.

### When to Use MiniMCP

- If you need to embed MCP in an existing web application (FastAPI, Django, Flask, etc.)
- Want stateless, horizontally scalable MCP servers
- Are deploying to serverless environments (AWS Lambda, Cloud Functions, etc.)
- Use your existing battle-tested security mechanisms and middlewares
- Want simple HTTP endpoints without mandatory bidirectional communication
- Need better CPU usage, and resilience by running multiple workers (e.g., `uvicorn --workers 4`)

### Currently Supported Features

The following features are already available in MiniMCP.

- 🧩 Server primitives - Tools, Prompts and Resources
- 🔗 Transports - stdio, HTTP, Streamable HTTP
- 🔄 Server to client messages - Progress notification
- 🛠 Typed scope and handler context
- ⚡ Asynchronous and stateless message processing
- 📝 Easy handler registration for different MCP message types
- ⏱️ Enforces idle time and concurrency limits
- 📦 Web frameworks — In-built support for Starlette/FastAPI

### Planned Features

These features may be added in the future if the need arises.

- ⚠️ Built-in support for more frameworks — Flask, Django etc.
- ⚠️ Client primitives - Sampling, Elicitation, Logging
- ⚠️ Resumable Streamable HTTP with GET method support
- ⚠️ Fine-grained access control (FGAC)
- ⚠️ Pagination
- ⚠️ Authentication
- ⚠️ MCP Client (_As shown in the [integration tests](https://github.com/cloudera/minimcp/blob/main/tests/integration/), MiniMCP (All 3 transports) works seamlessly with existing MCP clients, hence there is no immediate need for a custom client_)

### 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](https://github.com/cloudera/minimcp/blob/main/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:

```bash
# 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.

```python
# 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.

```bash
uv run uvicorn test:app --workers 4
```

### Basic Setup

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

```python
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:

```python
# 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.

```python
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`](https://github.com/jlowin/fastmcp) package (v3.1.1,
by Jeremiah Lowin) and the official MCP Python SDK [`mcp`](https://github.com/modelcontextprotocol/python-sdk)
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](https://github.com/cloudera/minimcp/blob/main/benchmarks/reports/BENCHMARK_ANALYSIS_REPORT.md).

### 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, idle_timeout is set to 30 seconds and max_concurrency to 100.

```python
# 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

```python
# 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

```python
# 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

```python
# 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`.

```python
# 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cloudera-minimcp
- Seller: https://agentstack.voostack.com/s/cloudera
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.