# grep-mcp Timeout Settings: How the MCP Server Handles API Timeouts and Errors

> Learn about grep-mcp timeout settings. Discover how the MCP server manages API timeouts and converts asyncio TimeoutError exceptions to cleaner GrepAPITimeoutError instances.

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

---

**The grep-mcp server enforces a 30-second global timeout on all HTTP requests to the grep.app API, converting low-level `asyncio.TimeoutError` exceptions into domain-specific `GrepAPITimeoutError` instances for cleaner error handling.**

The `grep-mcp` repository provides a Model Context Protocol (MCP) server that interfaces with the grep.app search API. Understanding the **timeout settings in grep-mcp** is critical for developers integrating this tool into latency-sensitive environments or handling unreliable network conditions.

## Timeout Configuration in grep-mcp

### Global 30-Second Timeout Setting

All network communication in `grep-mcp` occurs through an asynchronous HTTP client using `aiohttp`. The server initializes each `ClientSession` with a strict **30-second total timeout** that governs the entire request lifecycle, including connection establishment, request transmission, and response reading.

In [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py), the timeout is configured as follows:

```python
async with aiohttp.ClientSession(
    timeout=aiohttp.ClientTimeout(total=30)
) as session:
    ...

```

This configuration appears at lines 226-227 and ensures that no single API request can hang indefinitely, protecting server resources from zombie connections.

## Custom Timeout Exception Hierarchy

### GrepAPITimeoutError Class Definition

Rather than exposing implementation-specific exceptions to callers, `grep-mcp` defines a custom exception hierarchy that abstracts timeout failures. The `GrepAPITimeoutError` class extends the base `GrepAPIError` and specifically represents scenarios where the grep.app API fails to respond within the allotted time window.

The exception is declared near the top of [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py) (lines 26-28):

```python
class GrepAPITimeoutError(GrepAPIError):
    """Raised when grep.app API request times out."""

```

This design pattern allows downstream consumers to catch timeout-specific errors without depending on `asyncio` or `aiohttp` internals, improving code maintainability and testability.

## Error Handling and Propagation Strategy

### Catching asyncio.TimeoutError

When the underlying `aiohttp` request exceeds the 30-second threshold, the library raises `asyncio.TimeoutError`. The server implementation catches this low-level exception and immediately re-raises it as the domain-specific `GrepAPITimeoutError`, preserving the semantic meaning while adding context about the external service.

This translation occurs at lines 252-254 in [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py):

```python
except asyncio.TimeoutError:
    raise GrepAPITimeoutError("Request to grep.app API timed out")

```

### User-Facing Error Messages

The final layer of timeout handling occurs in the function that executes the search operation. Here, the code catches `GrepAPITimeoutError` and returns a formatted, user-friendly message rather than a raw stack trace or technical exception string.

At lines 258-259, the implementation provides clear feedback:

```python
except GrepAPITimeoutError:
    return "❌ Error: Request timed out. The grep.app API may be experiencing issues."

```

This approach ensures that end users receive actionable information about network failures without exposure to internal implementation details.

## Adjusting Timeout Values

While the default 30-second timeout suits most use cases, developers deploying `grep-mcp` in high-latency environments or processing large result sets may need to extend this threshold. The timeout value is passed directly to `aiohttp.ClientTimeout`, making customization straightforward.

To implement a 60-second timeout, modify the session initialization:

```python
import aiohttp

custom_timeout = aiohttp.ClientTimeout(total=60)

async with aiohttp.ClientSession(timeout=custom_timeout) as session:
    # Perform request with extended timeout

    ...

```

When adjusting timeouts, ensure that downstream exception handlers remain compatible with the `GrepAPITimeoutError` class to maintain consistent error semantics.

## Summary

- **grep-mcp** enforces a **30-second global timeout** on all HTTP requests via `aiohttp.ClientTimeout(total=30)` in [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py).
- Timeout failures are abstracted through the custom **`GrepAPITimeoutError`** exception, which extends the base `GrepAPIError` class.
- The implementation catches `asyncio.TimeoutError` from the underlying library and **re-raises it as `GrepAPITimeoutError`** to provide domain-specific context.
- End users receive **friendly error messages** indicating API issues rather than technical stack traces.
- Timeout values can be customized by modifying the `ClientTimeout` parameter when initializing the `aiohttp` session.

## Frequently Asked Questions

### What is the default timeout in grep-mcp?

The default timeout in grep-mcp is **30 seconds**, configured as a global total timeout on the `aiohttp.ClientSession`. This setting applies to the entire request lifecycle including connection, sending, and receiving data.

### How does grep-mcp handle timeout errors differently from standard asyncio errors?

Rather than exposing `asyncio.TimeoutError` directly to callers, grep-mcp **catches the low-level exception and re-raises it as `GrepAPITimeoutError`**. This domain-specific exception inherits from `GrepAPIError`, allowing downstream code to handle API failures consistently without depending on implementation details of the HTTP client library.

### Can I customize the timeout duration in grep-mcp?

Yes, you can customize the timeout by modifying the `aiohttp.ClientTimeout(total=...)` parameter in [`src/grep_mcp/server.py`](https://github.com/galprz/grep-mcp/blob/main/src/grep_mcp/server.py). While the default is 30 seconds, you can increase this value for high-latency networks or decrease it for faster failure detection in time-sensitive environments.

### Where is the timeout configuration documented for end users?

The 30-second network timeout is documented in the **Error Handling** section of the project's [`README.md`](https://github.com/galprz/grep-mcp/blob/main/README.md) file. This documentation explains that requests to the grep.app API may time out if the service is experiencing issues, providing users with context for the timeout behavior they might encounter.