# How grep-mcp Parses Command-Line Arguments to Select the Transport Mode

> Learn how grep-mcp parses command-line arguments using argparse to select transport mode. Discover supported modes like stdio and sse for efficient communication.

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

---

**The grep-mcp entry point uses Python's `argparse` module to parse the `--transport` flag, defaulting to `stdio` mode while supporting `sse` for web-based communication.**

The **grep-mcp** repository (`galprz/grep-mcp`) implements a Model Context Protocol (MCP) server that exposes grep functionality to AI assistants. When launching the server, the main entry point must determine whether to communicate via standard input/output or over HTTP using Server-Sent Events. This transport mode selection is handled through a robust command-line argument parsing system implemented in the core server module.

## Entry Point Architecture

The executable entry point follows a minimal bootstrap pattern that delegates all logic to the main server implementation.

### The [`__main__.py`](https://github.com/galprz/grep-mcp/blob/main/__main__.py) Bootstrap

The file [`src/grep_mcp/__main__.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/__main__.py) serves as the package entry point. It contains minimal boilerplate that imports and immediately invokes the `main()` function from the [`server.py`](https://github.com/galprz/grep-mcp/blob/main/server.py) module:

```python

# src/grep_mcp/__main__.py

from grep_mcp.server import main

main()

```

This separation of concerns ensures that argument parsing and server initialization logic resides in a dedicated module while maintaining a clean executable interface.

### Argument Parser Setup in [`server.py`](https://github.com/galprz/grep-mcp/blob/main/server.py)

Inside [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py), the `main()` function constructs an **`argparse.ArgumentParser`** instance and defines three critical parameters that control server behavior:

```python

# src/grep_mcp/server.py

import argparse

def main():
    parser = argparse.ArgumentParser(description='Grep MCP Server')
    parser.add_argument(
        '--transport',
        choices=['stdio', 'sse'],
        default='stdio',
        help='Transport mode (stdio or sse)'
    )
    parser.add_argument(
        '--host',
        default='0.0.0.0',
        help='Host to bind to (for SSE mode)'
    )
    parser.add_argument(
        '--port',
        type=int,
        default=8080,
        help='Port to listen on (for SSE mode)'
    )
    
    args = parser.parse_args()
    # Transport selection logic follows...

```

The **`--transport`** argument uses the `choices` constraint to restrict inputs to either `stdio` or `sse`, with `stdio` serving as the default for backward compatibility and CLI usage. The **`--host`** and **`--port`** arguments are typed specifically for the SSE transport mode, allowing users to configure the network binding when running the server as a web service.

## Transport Mode Selection Logic

After parsing completes, the `main()` function evaluates `args.transport` to determine which execution path to initialize. This branching logic cleanly separates the two transport implementations.

### Standard I/O Mode (stdio)

When `args.transport` equals `'stdio'` (the default), the server invokes the MCP instance's `run()` method with the transport parameter explicitly set:

```python

# src/grep_mcp/server.py

if args.transport == 'stdio':
    mcp.run(transport='stdio')

```

This mode establishes a **standard input/output** communication channel between the MCP server and its client (typically an AI assistant or IDE). The server reads JSON-RPC messages from `stdin` and writes responses to `stdout`, making it ideal for local process spawning and pipe-based integration.

### Server-Sent Events Mode (sse)

When the user specifies `--transport sse`, the server transitions to HTTP-based communication using **Server-Sent Events**. This path requires additional setup:

```python

# src/grep_mcp/server.py

elif args.transport == 'sse':
    from starlette.applications import Starlette
    import uvicorn
    
    # Create the Starlette application with SSE endpoints

    app = create_starlette_app(mcp)
    
    # Launch the Uvicorn server with configured host and port

    uvicorn.run(app, host=args.host, port=args.port)

```

In this mode, the `create_starlette_app()` function (defined elsewhere in the module) constructs a **Starlette** application that exposes the MCP endpoints over HTTP. The server then launches **Uvicorn** as the ASGI server, binding to the `host` and `port` values parsed from the command line. This transport mode enables remote clients to connect to the grep functionality over the network, supporting browser-based AI assistants or distributed architectures.

## Practical Usage Examples

The command-line interface supports both local CLI integration and network deployment scenarios.

Run the server in default stdio mode for local AI assistant integration:

```bash

# Default stdio mode (no flags required)

python -m grep_mcp

# Explicit stdio specification

python -m grep_mcp --transport stdio

```

Deploy the server as a web service with custom network binding:

```bash

# SSE mode with default host (0.0.0.0) and port (8080)

python -m grep_mcp --transport sse

# SSE mode with custom binding

python -m grep_mcp --transport sse --host 127.0.0.1 --port 9000

```

## Summary

- The **entry point** at [`src/grep_mcp/__main__.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/__main__.py) delegates to `main()` in [`server.py`](https://github.com/galprz/grep-mcp/blob/main/server.py), maintaining clean separation between bootstrap and logic.
- **Argument parsing** uses Python's `argparse` module to define `--transport`, `--host`, and `--port` parameters, with `stdio` as the default transport.
- **Transport selection** branches on `args.transport`: `stdio` mode invokes `mcp.run(transport='stdio')` for standard I/O, while `sse` mode constructs a Starlette application and launches Uvicorn with the configured host and port.
- The implementation supports both **local process integration** via pipes and **network deployment** via HTTP Server-Sent Events.

## Frequently Asked Questions

### What is the default transport mode when running grep-mcp without arguments?

The default transport mode is **stdio** (standard input/output). When you run `python -m grep_mcp` without specifying `--transport`, the argument parser automatically sets the transport to `stdio`, enabling immediate communication via pipes for local AI assistant integration.

### How do I run grep-mcp as a web server instead of a command-line tool?

To run grep-mcp as a web server, specify `--transport sse` when launching the module. This mode activates the Server-Sent Events transport, which creates a Starlette application and starts a Uvicorn server. You can optionally customize the network binding using `--host` and `--port` parameters.

### Why does the SSE transport mode require host and port arguments while stdio does not?

The **SSE** (Server-Sent Events) transport operates over HTTP, requiring a network socket to bind to a specific IP address and port number for incoming client connections. In contrast, **stdio** mode communicates through the process's standard input and output streams, which are already established by the operating system when the process starts, eliminating the need for network configuration.