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

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 and consumed by 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.

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.

export MCP_HTTP_ENABLED=true

This variable is defined at line 549 in config.py.

HTTPS Termination

To encrypt traffic, enable MCP_HTTPS_ENABLED (default: false) at line 557 in config.py. When active, the server listens for TLS connections and either uses auto-generated self-signed certificates or custom PEM files.

export MCP_HTTPS_ENABLED=true
export MCP_HTTPS_PORT=8443

If you omit certificate paths, 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.

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): Dedicated port for HTTPS (default: 8443).

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 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.

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).

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:

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:

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:

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:

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:

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:

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

Query Runtime Configuration

Verify effective settings via the REST API:

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

This endpoint returns the parsed JSON schema defined in 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 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 and 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 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 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 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).

Is the API key required for all endpoints when enabled?

Yes. When MCP_API_KEY is set in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}