# Configuring Timeout Settings for HTTP Requests in Python MCP Servers

> Learn how to configure HTTP request timeouts in Python MCP servers. Control timeouts via requests.get() parameter, module constants, or environment variables for flexible deployment.

- Repository: [CSK/mcp-wordle-python](https://github.com/cr2007/mcp-wordle-python)
- Tags: how-to-guide
- Published: 2026-02-28

---

**You can configure HTTP request timeouts in Python MCP servers by modifying the `timeout` parameter in the `requests.get()` call, using module-level constants for centralized control, or leveraging environment variables for deployment flexibility.**

The `cr2007/mcp-wordle-python` repository demonstrates how a FastMCP-based server handles external API calls using the Python `requests` library. Configuring timeout settings for HTTP requests in Python MCP servers is essential to prevent hanging processes and ensure reliable tool execution when calling external services like the Wordle API.

## Current Timeout Implementation

In [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py), the `get_wordle_data` function makes an HTTP request with a hardcoded timeout of **300 seconds** (5 minutes):

```python

# src/mcp_wordle/main.py (lines 66-67)

return requests.get(url, timeout=300).json()

```

This inline approach provides a safeguard against indefinite hangs but lacks flexibility for different deployment environments. The server entry point at lines 70-71 initializes the FastMCP server:

```python
if __name__ == "__main__":
    mcp.run()

```

Because MCP servers run as short-lived processes, the HTTP timeout serves as the primary defense against resource exhaustion when external APIs respond slowly.

## Three Methods to Configure HTTP Timeouts

Depending on your operational requirements, you can implement timeout configuration using three distinct approaches.

### Inline Argument Modification

The simplest method changes the timeout value directly in the `requests.get()` call. This approach works best for quick fixes or when the timeout requirement is truly static.

```python

# src/mcp_wordle/main.py

# Reduced from 300 seconds to 30 seconds

return requests.get(url, timeout=30).json()

```

While straightforward, this method requires code changes for every adjustment and scatters configuration logic throughout your source files.

### Module-Level Constants

Centralizing timeout values as constants improves maintainability. Define a module-level variable in [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py) and reference it across all HTTP requests:

```python

# src/mcp_wordle/main.py

DEFAULT_TIMEOUT = 30  # seconds

def get_wordle_data():
    # ...

    return requests.get(url, timeout=DEFAULT_TIMEOUT).json()

```

This approach consolidates configuration at the top of your file, making it easier to adjust timeouts during development without hunting through function implementations.

### Environment Variable Configuration

For production deployments using Docker or `uvx`, environment variables provide the most flexibility. Modify [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py) to read from `os.getenv()` with a sensible default:

```python

# src/mcp_wordle/main.py

import os

DEFAULT_TIMEOUT = int(os.getenv("WORDLE_TIMEOUT", "30"))

def get_wordle_data():
    # ...

    return requests.get(url, timeout=DEFAULT_TIMEOUT).json()

```

This method allows operators to adjust timeouts without rebuilding the container or modifying source code, which is critical for infrastructure-as-code workflows.

## Docker Deployment Configuration

When deploying via Docker (as documented in the repository's README), pass the timeout variable through the MCP server configuration:

```json
{
  "mcpServers": {
    "Wordle MCP (Python)": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--init",
        "-e", "WORDLE_TIMEOUT=45",
        "ghcr.io/cr2007/mcp-wordle-python:latest"
      ]
    }
  }
}

```

The [`pyproject.toml`](https://github.com/cr2007/mcp-wordle-python/blob/main/pyproject.toml) file confirms that `requests` is declared as a dependency (lines 7-10), ensuring that the `timeout` parameter is fully supported in the runtime environment.

## Balancing Timeout Settings

Adjusting timeout values requires balancing two competing concerns:

- **Responsiveness**: Setting timeouts too short may cause legitimate API responses to fail on slow or flaky networks, resulting in false errors for MCP tool calls.
- **Resource Usage**: Excessively long timeouts tie up the MCP process, delaying subsequent requests and potentially exhausting container resources during high-load scenarios.

The current 300-second default accommodates slow Wordle API responses but may be excessive for responsive deployments. Reducing this to 30-45 seconds typically provides adequate buffer while preventing resource starvation.

## Summary

- **Primary configuration location**: The timeout is set in [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py) within the `requests.get()` call at lines 66-67.
- **Inline modification**: Change the hardcoded value for quick adjustments, though this offers the least flexibility.
- **Constants approach**: Use module-level variables to centralize timeout configuration for easier maintenance.
- **Environment variables**: Implement `os.getenv()` patterns to allow runtime configuration without code changes, ideal for Docker deployments.
- **FastMCP compatibility**: Timeout adjustments do not affect the tool registration or function signatures, preserving compatibility with existing MCP clients.

## Frequently Asked Questions

### How do I change the HTTP timeout without modifying source code?

Set the `WORDLE_TIMEOUT` environment variable when launching the container. The server can read this variable using `os.getenv("WORDLE_TIMEOUT", "30")` to override default values, allowing configuration through your MCP client settings or Docker orchestration tools.

### What is the default timeout in the Wordle MCP server?

According to the source code in [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py), the default timeout is **300 seconds** (5 minutes), specified directly in the `requests.get(url, timeout=300)` call. This value accommodates potentially slow responses from the external Wordle API.

### Why does my MCP server hang when calling external APIs?

Without explicit timeout configuration, HTTP requests may wait indefinitely for server responses. Ensure your `requests.get()` calls include a `timeout` parameter, or implement the environment variable pattern described above to prevent the FastMCP process from hanging on unresponsive endpoints.

### Does changing the timeout affect the MCP tool registration?

No. Modifying the HTTP timeout value does not change the function signature of `get_wordle_data` or the FastMCP tool registration. The timeout operates internally within the function and remains transparent to the MCP protocol layer.