create_starlette_app in Grep-MCP: Building the SSE Web Interface

The create_starlette_app function constructs a Starlette ASGI application that exposes the Grep-MCP server over Server-Sent Events (SSE), enabling persistent HTTP connections for web-based clients.

The create_starlette_app function serves as the critical bridge between Grep-MCP's core functionality and modern web interfaces. Located in the galprz/grep-mcp repository, this factory function transforms the standard stdio-based MCP server into a web-accessible service using Starlette and Server-Sent Events. When users specify the --transport sse flag, create_starlette_app instantiates the necessary HTTP endpoints to handle real-time, bidirectional communication between browser clients and the grep-powered MCP server.

What is create_starlette_app?

The create_starlette_app function is an async factory defined in src/grep_mcp/server.py (lines 61-75) that generates a configured Starlette application instance. Its primary purpose is to wrap the MCP server with an HTTP interface capable of handling Server-Sent Events.

When Grep-MCP operates in SSE mode rather than the default stdio mode, it requires a long-lived HTTP connection that can stream messages continuously between the client and server. The create_starlette_app function establishes this infrastructure by integrating the MCP server with SseServerTransport, creating the necessary route handlers, and returning a fully configured ASGI application ready for deployment with uvicorn.

How create_starlette_app Works

The function operates through three distinct phases to establish the SSE web interface.

Instantiating the SSE Transport

First, create_starlette_app instantiates an SseServerTransport object with the base URL path /messages/. This transport layer handles the protocol-level details of Server-Sent Events, managing the connection lifecycle and message framing. The /messages/ endpoint serves as the POST target where clients send messages to the MCP server.

Handling SSE Connections

The core logic resides in the async handle_sse function defined within create_starlette_app. This handler:

1. Accepts incoming HTTP requests to the /sse endpoint
2. Connects the SSE transport to the request's ASGI scope
3. Establishes read/write streams for bidirectional communication
4. Starts the MCP server with the transport streams and initialization options

The handler maintains the persistent connection required for real-time updates, allowing the grep-based MCP tools to stream results back to web clients as they become available.

Registering HTTP Routes

Finally, the function constructs and returns a Starlette application configured with two critical routes:

• /sse: Mounted to the handle_sse handler, this endpoint establishes the Server-Sent Events connection
• /messages/: Mounted via SseServerTransport, this endpoint receives POST requests from clients containing MCP protocol messages

The returned Starlette instance is a fully functional ASGI application that can be served by uvicorn or any compatible ASGI server.

Using create_starlette_app in Practice

The function supports both command-line and programmatic usage patterns.

Command-Line SSE Mode

When launching Grep-MCP with the SSE transport flag, the main() function (lines 38-44 in src/grep_mcp/server.py) automatically invokes create_starlette_app:

python -m grep_mcp --transport sse --host 0.0.0.0 --port 8080

This command triggers the following chain: main() → create_starlette_app(mcp_server, debug=True) → uvicorn serves the returned Starlette application on the specified host and port.

Programmatic Usage

Developers can embed the SSE-enabled server directly in Python applications:

from grep_mcp.server import mcp, create_starlette_app
import uvicorn

# Access the internal MCP server instance from FastMCP

mcp_server = mcp._mcp_server

# Build the Starlette application (debug mode optional)

app = create_starlette_app(mcp_server, debug=False)

# Serve with uvicorn

uvicorn.run(app, host="127.0.0.1", port=8000)

This pattern allows integration of Grep-MCP's grep functionality into existing web services or custom deployment scenarios.

Client-Side Connection

Web clients connect to the SSE endpoint using standard EventSource APIs:

const evtSource = new EventSource("http://localhost:8000/sse");

evtSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("MCP message:", data);
};

evtSource.onerror = (err) => {
  console.error("SSE error:", err);
};

The client listens on /sse for server-sent messages, while posting responses to /messages/ to complete the bidirectional communication loop with the MCP server.

Source Code Location

The create_starlette_app function is implemented in src/grep_mcp/server.py at lines 61-75. It is invoked by the main() function at lines 38-44 when the --transport sse command-line argument is specified. The implementation depends on the mcp package's SseServerTransport class and Starlette's routing and application classes.

Summary

• create_starlette_app constructs a Starlette web application that exposes Grep-MCP over Server-Sent Events
• The function is defined in src/grep_mcp/server.py (lines 61-75) and bridges the MCP server with HTTP-based clients
• It configures two critical endpoints: /sse for establishing event streams and /messages/ for receiving client posts
• The function enables the --transport sse mode, allowing Grep-MCP to run as a persistent web service accessible to browser-based clients
• When invoked programmatically, it returns a fully configured ASGI application ready for deployment with uvicorn

Frequently Asked Questions

What does create_starlette_app do in Grep-MCP?

The create_starlette_app function builds a Starlette ASGI application that wraps the Grep-MCP server with Server-Sent Events support. It creates the HTTP infrastructure necessary for web clients to establish persistent connections and exchange MCP protocol messages over standard HTTP, enabling browser-based interaction with the grep functionality.

How do I run Grep-MCP using the SSE transport created by create_starlette_app?

Launch the server from the command line with the --transport sse flag: python -m grep_mcp --transport sse --host 0.0.0.0 --port 8080. This triggers the main() function to call create_starlette_app, which constructs the Starlette application and serves it via uvicorn on the specified host and port.

What endpoints does create_starlette_app configure?

The function configures two essential HTTP endpoints: /sse handles GET requests to establish the Server-Sent Events stream, while /messages/ accepts POST requests from clients sending MCP protocol messages. These endpoints work together to provide bidirectional communication between web clients and the Grep-MCP server core.

Can I use create_starlette_app in my own Python applications?

Yes, you can import and invoke create_starlette_app programmatically to embed Grep-MCP's SSE capabilities into custom web services. Import the function from grep_mcp.server, pass the MCP server instance and optional debug flag, and receive a fully configured Starlette ASGI application ready to run with uvicorn or any ASGI-compatible server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}