This server acts as a lightweight HTTP/STDIO gateway that exposes Python functions as discoverable and executable tools under the Model Context Protocol (MCP). It enables remote tool execution via JSON-RPC interface with both stateful and stateless contexts.
Key Capabilities:
Remote Tool Execution: Execute Python functions remotely through HTTP POST requests or STDIO
Tool Discovery: Discover available tools and their specifications via the MCP protocol
Dual Context Support: Maintain state across tool calls (stateful) or access incoming request data like headers and cookies (stateless)
Type-Safe Validation: Uses Pydantic for robust input/output schema validation and serialization
Asynchronous Handling: Provides async request processing via Starlette or FastAPI
Example Tools:
get_weather
: Retrieve weather data for specified locations with temperature unit optionsget_time
: Fetch current timetool_that_access_request
: Access request details like username from headersget_called_tools
: Retrieve list of previously called tools using stateful context
Provides a framework for building HTTP-based MCP servers that can be integrated into FastAPI applications, enabling the exposure of Python functions as discoverable tools and prompts
Uses Pydantic models for type-safe data validation and serialization of tool inputs, outputs, and server configurations
Simple HTTP MCP Server Implementation
This project provides a lightweight server implementation for the Model Context Protocol (MCP) over HTTP. It allows you to expose Python functions as tools and prompts that can be discovered and executed remotely via a JSON-RPC interface. It is intended to be used with a Starlette or FastAPI application (see demo).
The following badge corresponds to the example server for this project. Find it in the tests/app/ folder.
Features
- MCP Protocol Compliant: Implements the MCP specification for tool and prompts discovery and execution. No support for notifications.
- HTTP and STDIO Transport: Uses HTTP (POST requests) or STDIO for communication.
- Async Support: Built on
Starlette
orFastAPI
for asynchronous request handling. - Type-Safe: Leverages
Pydantic
for robust data validation and serialization. - Server State Management: Access shared state through the lifespan context
using the
get_state_key
method. - Request Access: Access the incoming request object from your tools and prompts.
Server Architecture
The library provides a single MCPServer
class that uses lifespan to manage
shared state across the entire application lifecycle.
MCPServer
The MCPServer
is designed to work with Starlette's lifespan system for
managing shared server state.
Key Characteristics:
- Lifespan Based: Uses Starlette's lifespan events to initialize and manage shared server state
- Application-Level State: State persists across the entire application lifecycle, not per-request
- Flexible: Can be used with any custom context class stored in the lifespan state
Example Usage:
Tools
Tools are the functions that can be called by the client.
Example:
- Define the arguments and output for the tools:
- Define the tools:
- Instantiate the server:
Server State Management
The server uses Starlette's lifespan system to manage shared state across the
entire application lifecycle. State is initialized when the application starts
and persists until it shuts down. Context is accessed through the
get_state_key
method on the Arguments
object.
Example:
- Define a context class:
- Set up the application with lifespan:
- Access the context in your tools:
Request Access
You can access the incoming request object from your tools. The request object is passed to each tool call and can be used to access headers, cookies, and other request data (e.g. request.state, request.scope).
Prompts
You can add interactive templates that are invoked by user choice. Prompts now support lifespan state access, similar to tools.
- Define the arguments for the prompts:
- Using prompts with lifespan state:
- Instantiate the server:
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A lightweight server implementation that exposes Python functions as discoverable tools via HTTP using the Machine-to-Machine Communication Protocol (MCP). Enables remote execution of Python functions through a JSON-RPC interface with async support and type safety.
Related MCP Servers
- -securityFlicense-qualityThis is an MCP server that facilitates building tools for interacting with various APIs and workflows, supporting Python-based development with potential for customizable prompts and user configurations.Last updated -
- AsecurityAlicenseAqualityA server that provides a persistent Python REPL environment through the MCP protocol, allowing execution of Python code, variable management, and package installation.Last updated -326MIT License
- -securityFlicense-qualityA Python implementation of the MCP server that enables AI models to connect with external tools and data sources through a standardized protocol, supporting tool invocation and resource access via JSON-RPC.Last updated -1
- -securityFlicense-qualityA Python template for building Model Context Protocol (MCP) servers that expose tools via JSON-RPC, enabling secure and scalable context and tool invocation for language models.Last updated -