flask

This MCP server provides a unified HTTP endpoint for interacting with a Python-based MCP registry built on Flask. It exposes a single /mcp endpoint that accepts JSON-RPC requests via POST and can stream responses using Server-Sent Events (SSE) when the client requests text/event-stream. The server supports legacy endpoints for backward compatibility, including /mcp/list, /mcp/call, and /mcp/batch. You can run the dedicated standalone server (serve-http) to expose docs at Swagger and OpenAPI at /docs.json, or embed the MCP functionality directly into an existing Flask application by mounting the MCP component. Tools, resources, prompts, and completions are registered via decorators or a registry facade, and you can interact with them via the unified endpoint or through the backwards-compatible routes.

To use the endpoint, send a JSON-RPC 2.0 payload to /mcp with a valid MCP protocol version header (MCP-Protocol-Version: 2025-06-18). For a standard request, you’ll get a JSON response; for streaming you can set Accept: text/event-stream to receive an SSE stream. If you initialize a session by posting an initialize method, the server may return a Mcp-Session-Id header for subsequent requests. You can also configure authentication (API keys or HMAC), rate limiting, and CORS policies via environment variables. The tools are discovered and invoked via the Mcp.tool decorator or registry facade, supporting role-based access and TTL-based memoization where configured.

Prerequisites:

• Python 3.9+ installed on your system
• pip available for installing Python packages

Install the MCP server package from PyPI:

pip install flask-mcp-server

Option A: Run as a standalone dedicated server (HTTP endpoint)

1. Install as above
2. Run the server (example using the provided CLI entry point via the module):

python -m flask_mcp_server serve-http

3. The server will listen on the default port (usually 8765). You can configure host/port via environment or command-line flags if provided by the package.

Option B: Integrate into an existing Flask app

1. Install as above
2. In your Flask app, import and mount MCP using the provided helpers:

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_mcp(app, url_prefix="/mcp", middlewares=[mw_auth, mw_ratelimit, mw_cors])

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

3. Run your Flask app as you normally would (e.g., python app.py). The MCP endpoints will be available under /mcp.

Tips:

• If you enable API keys or HMAC, ensure keys/secrets are kept secure and not checked into version control.
• For SSE streams, clients should throttle reads to handle ongoing events without backpressure.
• The Unified MCP endpoint supports both JSON-RPC styles and SSE streaming; when Accept includes text/event-stream, responses are streamed.
• The 2025-06-18 protocol header is required for full feature support; older back-compat paths remain for legacy clients.
• Review environment variables to tune security (FLASK_MCP_AUTH_MODE, FLASK_MCP_RATE_LIMIT, etc.).
• If using TTL caching, configure ttl on tools/resources to avoid unnecessary recomputation.
• When embedding in an existing app, ensure your Flask app’s middleware stack does not conflict with MCP middlewares (auth, rate limiting, CORS).
• For debugging, open the Swagger UI at /swagger and the OpenAPI spec at /docs.json when running the dedicated server.