# create_starlette_app in Grep-MCP: Building the SSE Web Interface

> Discover how create_starlette_app in Grep-MCP builds an SSE web interface. This function exposes the Grep-MCP server via persistent HTTP connections for web clients, enhancing real-time data flow.

- Repository: [gal peretz/grep-mcp](https://github.com/galprz/grep-mcp)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py)) automatically invokes `create_starlette_app`:

```bash
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:

```python
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:

```javascript
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`](https://github.com/galprz/grep-mcp/blob/main/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`](https://github.com/galprz/grep-mcp/blob/main/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.