mcp-streamable-http

The mcp-streamable-http-server provides a Streamable HTTP MCP service with authentication, session management, and tool execution. It supports dynamic service registration, context-aware user identification, and configurable middleware for access control and custom logic. Tools are defined via Python implementations and YAML configurations, enabling you to expose specific MCP capabilities (like demo routines, notifications, or session-related operations) to MCP inspectors and clients. To use it, start the server (the project is Python-based and recommended to run with uv), configure environment variables for your database and host, and then interact with the exposed Tools through your MCP client or the MCP Inspector to invoke actions and receive structured results.

Prerequisites:

• Python 3.13+ installed
• Git installed
• Optional: uv (recommended) for running the server

1. Clone the repository:

git clone https://github.com/purity3/mcp-streamable-http-server.git
cd mcp-streamable-http-server

2. Create and activate a virtual environment (recommended):

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate

3. Install development dependencies (via uv):

uv pip install -e .[dev]

4. Copy and customize environment configuration:

cp .env.example .env

Edit .env to set DATABASE_URL, HOST, PORT, and any other environment variables as needed. For SQLite, a typical setting is:

DATABASE_URL="sqlite:///./database.db"
HOST="0.0.0.0"
PORT="3000"

5. Run the server (uv recommended):

uv run server

6. Verify the server is accessible at the configured host/port, e.g. http://localhost:3000. You can connect with the MCP Inspector to test Tools, Resources, and Prompts.

Tips and common considerations:

• The server uses a middleware-based authentication flow; ensure your credentials and tokens are correctly configured in the client calls or via env vars.
• For SQLite databases, the database file (database.db) is typically created on first access if the path in DATABASE_URL is valid.
• When debugging with the MCP Inspector, set Transport Type to streamable-http and provide your server URL and credentials if required.
• If you enable dynamic service registration at runtime, make sure your YAML tool definitions are valid and accessible by the server.
• You can customize middleware and services to enforce IP-based access, advanced token validation, or logging as described in the README examples.