# How to Configure MCP Memory Service Startup and HTTP Mode: Complete Environment Variable Guide

> Configure MCP Memory Service startup and HTTP mode using environment variables. This guide details essential settings for server activation, port binding, and authentication.

- Repository: [Henry/mcp-memory-service](https://github.com/doobidoo/mcp-memory-service)
- Tags: how-to-guide
- Published: 2026-02-28

---

**The MCP Memory Service controls all server startup behavior—including HTTP/HTTPS activation, port binding, TLS certificates, and authentication—exclusively through environment variables parsed in [`src/mcp_memory_service/config.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/config.py) and consumed by [`run_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/run_server.py).**

The `doobidoo/mcp-memory-service` repository implements a persistent memory backend for the Model Context Protocol (MCP). Whether you run the server as a standalone gRPC service or enable the FastAPI web interface, every aspect of MCP server startup and HTTP mode configuration is driven by runtime environment variables.

## Server Activation: Enabling HTTP and HTTPS

The service operates in two distinct transport modes controlled by boolean toggles in [`src/mcp_memory_service/config.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/config.py).

### HTTP Mode Activation

Set **`MCP_HTTP_ENABLED`** to `true` (default: `false`) to start the FastAPI web server alongside the core MCP API. When disabled, only the pure gRPC interface runs.

```bash
export MCP_HTTP_ENABLED=true

```

This variable is defined at line 549 in [`config.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/config.py).

### HTTPS Termination

To encrypt traffic, enable **`MCP_HTTPS_ENABLED`** (default: `false`) at line 557 in [`config.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/config.py). When active, the server listens for TLS connections and either uses auto-generated self-signed certificates or custom PEM files.

```bash
export MCP_HTTPS_ENABLED=true
export MCP_HTTPS_PORT=8443

```

If you omit certificate paths, [`run_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/run_server.py) automatically generates certificates in `~/.mcp_memory_certs/`.

## Network Binding and Port Configuration

Control where the server listens using host and port variables validated in [`config.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/config.py).

### Interface and Port Settings

- **`MCP_HTTP_HOST`** (line 551): Interface address (default: `0.0.0.0`). Use `127.0.0.1` for local-only access.
- **`MCP_HTTP_PORT`** (line 550): TCP port for HTTP traffic (default: `8000`).
- **`MCP_HTTPS_PORT`** (line 30 in [`run_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/run_server.py)): Dedicated port for HTTPS (default: `8443`).

```bash
export MCP_HTTP_HOST=127.0.0.1
export MCP_HTTP_PORT=8080
export MCP_HTTPS_PORT=443

```

## Security Configuration: TLS, API Keys, and CORS

Production deployments require additional security controls parsed at startup.

### TLS Certificate Paths

Provide custom certificates via:
- **`MCP_SSL_CERT_FILE`** (line 558): Path to PEM-encoded certificate.
- **`MCP_SSL_KEY_FILE`** (line 559): Path to matching private key.

If these are unset while `MCP_HTTPS_ENABLED=true`, the server auto-generates self-signed certificates. If set but files are missing, [`run_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/run_server.py) terminates with an error (lines 38-44).

### API Key Authentication

Enable header-based authentication with **`MCP_API_KEY`** (line 554). When set, every request must include the `X-API-Key` header or `?api_key=` query parameter.

```bash
export MCP_API_KEY=super-secret-key

```

The key is never logged, preserving confidentiality during startup.

### CORS Origins

Restrict browser cross-origin requests using **`MCP_CORS_ORIGINS`** (line 552). Default is `*` (allow all).

```bash
export MCP_CORS_ORIGINS="https://app.example.com,https://admin.example.com"

```

## Service Discovery with mDNS

The server advertises itself via multicast DNS for local network discovery.

- **`MCP_MDNS_ENABLED`** (line 562): Boolean to enable advertisement (default: `true`).
- **`MCP_MDNS_SERVICE_NAME`** (line 563): Human-readable name (default: `MCP Memory Service`).
- **`MCP_MDNS_SERVICE_TYPE`** (line 564): Service identifier (default: `_mcp-memory._tcp.local.`).
- **`MCP_MDNS_DISCOVERY_TIMEOUT`** (line 565): Client wait time in seconds (default: `5`).

## Server-Sent Events (SSE) Transport

The dashboard uses an internal SSE channel configured separately from the main HTTP interface.

- **`MCP_SSE_HOST`** (line 545): Bind address for SSE (default: `127.0.0.1`).
- **`MCP_SSE_PORT`** (line 546): Port for SSE transport (default: `8765`).
- **`MCP_SSE_HEARTBEAT`** (line 553): Keep-alive interval in seconds (default: `30`, range: 5-300).

## Practical Startup Examples

### Start Basic HTTP Server

Enable the web UI on all interfaces using defaults:

```bash
export MCP_HTTP_ENABLED=true
export MCP_HTTP_HOST=0.0.0.0
export MCP_HTTP_PORT=8000
uv run python run_server.py

```

### Enable HTTPS with Auto-Generated Certificates

Run HTTPS without managing certificate files:

```bash
export MCP_HTTP_ENABLED=false
export MCP_HTTPS_ENABLED=true
export MCP_HTTPS_PORT=8443
uv run python run_server.py

```

The logs will display `Generating self-signed certificate for HTTPS...` on first start.

### Use Custom TLS Certificates

Terminate TLS using your own infrastructure certificates:

```bash
export MCP_HTTPS_ENABLED=true
export MCP_HTTPS_PORT=443
export MCP_SSL_CERT_FILE=/etc/ssl/certs/mycert.pem
export MCP_SSL_KEY_FILE=/etc/ssl/private/mykey.pem
uv run python run_server.py

```

The server validates file existence immediately and exits if paths are invalid.

### Protect with API Key and Restrict CORS

Secure a production instance:

```bash
export MCP_HTTP_ENABLED=true
export MCP_API_KEY=production-key-2024
export MCP_CORS_ORIGINS="https://memory.example.com"
export MCP_HTTP_PORT=8000
uv run python run_server.py

```

Clients must include `X-API-Key: production-key-2024` in every request.

### Docker Compose Deployment

Pass configuration via environment variables in [`tools/docker/docker-compose.http.yml`](https://github.com/doobidoo/mcp-memory-service/blob/main/tools/docker/docker-compose.http.yml):

```yaml
services:
  mcp-memory:
    environment:
      - MCP_HTTP_ENABLED=true
      - MCP_HTTP_PORT=8000
      - MCP_HTTP_HOST=0.0.0.0
      - MCP_HTTPS_ENABLED=false
    ports:
      - "8000:8000"

```

Start with:

```bash
docker compose -f tools/docker/docker-compose.http.yml up -d

```

### Query Runtime Configuration

Verify effective settings via the REST API:

```bash
curl http://localhost:8000/api/configuration | jq .

```

This endpoint returns the parsed JSON schema defined in [`src/mcp_memory_service/web/api/configuration.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/configuration.py), reflecting the actual environment variable values loaded at startup.

## Summary

- **Server mode control**: `MCP_HTTP_ENABLED` and `MCP_HTTPS_ENABLED` in [`config.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/config.py) determine whether the FastAPI interface starts and whether it uses TLS.
- **Network binding**: `MCP_HTTP_HOST`, `MCP_HTTP_PORT`, and `MCP_HTTPS_PORT` (defined in [`config.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/config.py) and [`run_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/run_server.py)) control listener addresses.
- **TLS options**: Either auto-generate certificates or supply custom paths via `MCP_SSL_CERT_FILE` and `MCP_SSL_KEY_FILE`.
- **Security layers**: Add `MCP_API_KEY` for authentication and `MCP_CORS_ORIGINS` for browser security.
- **Discovery and transport**: mDNS settings and SSE ports are independently configurable for local network visibility and dashboard real-time updates.
- **Startup entry point**: [`run_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/run_server.py) consumes these variables directly from `os.environ` to configure `uvicorn.run()` parameters.

## Frequently Asked Questions

### What happens if I set `MCP_HTTP_ENABLED=false`?

The server starts in gRPC-only mode without the FastAPI web interface. Only the core MCP protocol is available, and the dashboard, REST API endpoints, and web UI are inaccessible. This mode is suitable for headless deployments where clients connect directly via the MCP protocol.

### Can I run HTTP and HTTPS simultaneously on different ports?

The current [`run_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/run_server.py) implementation (lines 30-44) selects a single transport mode based on `MCP_HTTPS_ENABLED`. When HTTPS is enabled, it binds to `MCP_HTTPS_PORT` (default 8443). When disabled, it uses `MCP_HTTP_PORT` (default 8000). To run both simultaneously, you must launch separate instances with different environment variable sets.

### How does the server handle missing TLS certificate files?

If `MCP_HTTPS_ENABLED=true` but `MCP_SSL_CERT_FILE` and `MCP_SSL_KEY_FILE` are unset, [`run_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/run_server.py) automatically generates self-signed certificates in `~/.mcp_memory_certs/`. However, if you explicitly set these variables to file paths that do not exist, the server terminates immediately during startup with a validation error (lines 38-44 in [`run_server.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/run_server.py)).

### Is the API key required for all endpoints when enabled?

Yes. When `MCP_API_KEY` is set in [`config.py`](https://github.com/doobidoo/mcp-memory-service/blob/main/config.py) (line 554), every HTTP request must include the key via the `X-API-Key` header or `api_key` query parameter. This applies uniformly to the REST API, SSE endpoints, and dashboard resources. The gRPC interface operates independently and is not affected by this setting.