flask-mcp-server

Flask-based Model Context Protocol (MCP) server for Python. Drop it into any Flask app or run it standalone. Ships with security and ops features out of the box.

Spec target: MCP 2025-06-18 — Streamable HTTP transport with a unified /mcp endpoint (POST for JSON-RPC; GET for SSE). Back-compat routes retained.

Package version: 0.6.1

Table of Contents

• Requirements
• Install
• Quick Start
• What’s new in 0.6.1
• Configuration (env vars)
• Core Concepts
• Examples
  • A. Unified MCP endpoint usage
  • B. Tools with roles & TTL cache
  • C. Resources & ResourceTemplates
  • D. Prompts & Completions
  • E. Batch Calls (compat)
  • F. SSE (hello + registry events)
  • G. Auth: API keys & HMAC
  • H. Rate limiting
  • I. Service Providers
  • J. Discovery (auto-register)
  • K. CLI
  • L. OpenAPI & Swagger
• FAQ
• Troubleshooting
• License

Requirements

• Python 3.9+
• Flask 3.x (auto-installed)

Install

From PyPI

pip install flask-mcp-server

Add to requirements.txt from a file path:

flask-mcp-server==0.6.1

Quick Start

Integrated into an existing Flask app (integrated HTTP):

from flask import Flask
from flask_mcp_server import mount_mcp, Mcp
from flask_mcp_server.http_integrated import mw_auth, mw_ratelimit, mw_cors

app = Flask(__name__)

@Mcp.tool(name="sum")
def sum_(a: int, b: int) -> int:
    return a + b

# Mount at /mcp with useful middlewares
mount_mcp(app, url_prefix="/mcp", middlewares=[mw_auth, mw_ratelimit, mw_cors])

if __name__ == "__main__":
    app.run(port=8765)

Dedicated server app (ships with docs endpoints):

flask-mcp serve-http
# Swagger: http://127.0.0.1:8765/swagger
# OpenAPI: /docs.json

STDIO transport:

flask-mcp serve-stdio

What’s new in 0.6.1

• Unified MCP endpoint (/mcp):
  • POST a single JSON-RPC message (request/notification/response). If the Accept header includes text/event-stream, the server streams the response via SSE; otherwise returns JSON.
  • GET to open an SSE stream for server messages (optional). Supports Last-Event-ID for resumability in future minor releases.
• Protocol header: Accepts MCP-Protocol-Version: 2025-06-18 (or 2025-03-26 for back-compat); others => 400 Bad Request.
• Sessions (minimal): If the POSTed method is "initialize", response includes Mcp-Session-Id header. Clients can include this header on subsequent requests.
• Origin validation: Optional FLASK_MCP_ALLOWED_ORIGINS (comma-separated). If set, only requests with matching Origin are allowed at the unified MCP endpoint.
• Backwards compatibility: legacy endpoints /mcp/list, /mcp/call, /mcp/batch remain.

Configuration (env vars)

Auth & roles

export FLASK_MCP_AUTH_MODE=apikey     # none|apikey|hmac
export FLASK_MCP_API_KEYS="k1,k2"
export FLASK_MCP_API_KEYS_MAP="k1:admin|user;k2:user"   # per-key roles
export FLASK_MCP_HMAC_SECRET="supersecret"              # if using HMAC

Rate limiting

export FLASK_MCP_RATE_LIMIT=60/m      # format: <N>/<s|m|h|d>
export FLASK_MCP_RATE_SCOPE=key       # ip|key

CORS, Origins & Logging

export FLASK_MCP_ALLOWED_ORIGINS="http://localhost:3000,https://your.app"
export FLASK_MCP_CORS_ORIGIN="*"
export FLASK_MCP_LOG_FORMAT=json

Providers autoload

export FLASK_MCP_PROVIDERS="my_pkg.mcp_provider:Provider,another.mod:Pro

... [View full README on GitHub](https://github.com/bashar94/flask-mcp-server#readme)