polygon-io · jdconley · Aug 13, 2025 · Aug 15, 2025
diff --git a/Dockerfile b/Dockerfile
@@ -12,4 +12,38 @@ RUN chmod +x entrypoint.py
 
 ENV PYTHONPATH=/app/src:$PYTHONPATH
 
+# Polygon MCP Server Configuration
+# These environment variables can be overridden at runtime
+
+# Required - Must be provided at runtime
+# ENV POLYGON_API_KEY=your_api_key_here
+
+# Transport Configuration
+# Options: stdio (default), sse, streamable-http
+ENV MCP_TRANSPORT=stdio
+
+# Server Settings
+# Enable debug mode (true/false)
+ENV MCP_DEBUG=false
+# Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL
+ENV MCP_LOG_LEVEL=INFO
+
+# HTTP Settings (used for SSE and Streamable-HTTP transports)
+# Host/IP address to bind to (use 0.0.0.0 for all interfaces)
+ENV MCP_HOST=127.0.0.1
+# Port to bind to
+ENV MCP_PORT=8000
+
+# SSE-Specific Settings (only used when MCP_TRANSPORT=sse)
+# Mount path for the application (e.g., "/api", "/github")
+ENV MCP_MOUNT_PATH=/
+# SSE endpoint path
+ENV MCP_SSE_PATH=/sse
+# Message endpoint path
+ENV MCP_MESSAGE_PATH=/messages/
+
+# Streamable-HTTP-Specific Settings (only used when MCP_TRANSPORT=streamable-http)
+# Streamable HTTP endpoint path
+ENV MCP_STREAMABLE_HTTP_PATH=/mcp
+
 ENTRYPOINT ["uv", "run", "./entrypoint.py"]
diff --git a/ENV_VARIABLES.md b/ENV_VARIABLES.md
@@ -0,0 +1,158 @@
+# Environment Variables
+
+The Polygon MCP server can be configured using the following environment variables:
+
+## Required
+
+- `POLYGON_API_KEY`: Your Polygon.io API key (required for API access)
+
+## Transport Configuration
+
+- `MCP_TRANSPORT`: Transport protocol to use
+  - `stdio` (default) - Standard input/output
+  - `sse` - Server-Sent Events
+  - `streamable-http` - Streamable HTTP
+
+## Server Settings
+
+- `MCP_DEBUG`: Enable debug mode
+  - Values: `true`, `1`, `yes`, `on` (enables debug)
+  - Default: `false`
+
+- `MCP_LOG_LEVEL`: Logging level
+  - Values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+  - Default: `INFO`
+
+## HTTP Settings (for SSE and Streamable-HTTP transports)
+
+- `MCP_HOST`: Host/IP address to bind to
+  - Default: `127.0.0.1`
+  - Example: `0.0.0.0` (bind to all interfaces)
+
+- `MCP_PORT`: Port to bind to
+  - Default: `8000`
+  - Example: `9000`
+
+## SSE-Specific Settings
+
+These settings only apply when using the SSE transport:
+
+- `MCP_MOUNT_PATH`: Mount path for the application
+  - Default: `/`
+  - Example: `/github`
+
+- `MCP_SSE_PATH`: SSE endpoint path
+  - Default: `/sse`
+
+- `MCP_MESSAGE_PATH`: Message endpoint path
+  - Default: `/messages/`
+
+## Streamable-HTTP-Specific Settings
+
+These settings only apply when using the Streamable-HTTP transport:
+
+- `MCP_STREAMABLE_HTTP_PATH`: Streamable HTTP endpoint path
+  - Default: `/mcp`
+
+- `MCP_JSON_RESPONSE`: Return plain JSON instead of JSONRPC format
+  - Values: `true`, `1`, `yes`, `on` (enables JSON response mode)
+  - Default: `false`
+  - When enabled, returns raw JSON responses instead of JSONRPC wrapped responses
+
+- `MCP_STATELESS_HTTP`: Use stateless mode (new transport per request)
+  - Values: `true`, `1`, `yes`, `on` (enables stateless mode)
+  - Default: `false`
+  - When enabled, creates a new transport connection for each request instead of maintaining state
+
+## Example Usage
+
+### Running with stdio transport (default)
+```bash
+export POLYGON_API_KEY=your_api_key_here
+uv run entrypoint.py
+```
+
+### Running with SSE transport
+```bash
+export POLYGON_API_KEY=your_api_key_here
+export MCP_TRANSPORT=sse
+export MCP_HOST=0.0.0.0
+export MCP_PORT=9000
+export MCP_LOG_LEVEL=DEBUG
+uv run entrypoint.py
+```
+
+### Running with Streamable-HTTP transport
+```bash
+export POLYGON_API_KEY=your_api_key_here
+export MCP_TRANSPORT=streamable-http
+export MCP_HOST=0.0.0.0
+export MCP_PORT=3000
+export MCP_STREAMABLE_HTTP_PATH=/api/mcp
+uv run entrypoint.py
+```
+
+### Running with Streamable-HTTP in JSON response mode
+```bash
+export POLYGON_API_KEY=your_api_key_here
+export MCP_TRANSPORT=streamable-http
+export MCP_HOST=0.0.0.0
+export MCP_PORT=3000
+export MCP_JSON_RESPONSE=true
+export MCP_STATELESS_HTTP=true
+uv run entrypoint.py
+```
+
+### Docker Examples
+
+#### Building with custom defaults in Dockerfile
+```dockerfile
+ENV POLYGON_API_KEY=your_api_key_here
+ENV MCP_TRANSPORT=streamable-http
+ENV MCP_HOST=0.0.0.0
+ENV MCP_PORT=8080
+ENV MCP_LOG_LEVEL=INFO
+ENV MCP_DEBUG=false
+```
+
+#### Running with docker run
+```bash
+# Basic run with API key
+docker run -e POLYGON_API_KEY=your_api_key_here mcp-polygon
+
+# Run with SSE transport on all interfaces
+docker run -e POLYGON_API_KEY=your_api_key_here \
+  -e MCP_TRANSPORT=sse \
+  -e MCP_HOST=0.0.0.0 \
+  -e MCP_PORT=9000 \
+  -p 9000:9000 \
+  mcp-polygon
+
+# Run with Streamable-HTTP and debug logging
+docker run -e POLYGON_API_KEY=your_api_key_here \
+  -e MCP_TRANSPORT=streamable-http \
+  -e MCP_HOST=0.0.0.0 \
+  -e MCP_LOG_LEVEL=DEBUG \
+  -e MCP_STREAMABLE_HTTP_PATH=/api/mcp \
+  -p 8000:8000 \
+  mcp-polygon
+
+# Run with Streamable-HTTP in JSON response and stateless mode
+docker run -e POLYGON_API_KEY=your_api_key_here \
+  -e MCP_TRANSPORT=streamable-http \
+  -e MCP_HOST=0.0.0.0 \
+  -e MCP_JSON_RESPONSE=true \
+  -e MCP_STATELESS_HTTP=true \
+  -p 8000:8000 \
+  mcp-polygon
+```
+
+#### Using docker-compose
+See [docker-compose.yml](docker-compose.yml) for a complete example with all configurable environment variables.
+
+## Notes
+
+- The `host` and `port` settings are only used for HTTP-based transports (SSE and Streamable-HTTP)
+- When using `stdio` transport, HTTP settings are ignored
+- Path settings are transport-specific and only apply to their respective transports
+- Debug mode and log level apply to all transport types
diff --git a/README.md b/README.md
@@ -96,16 +96,68 @@ Make sure you complete the various fields.
 ```
 </details>
 
-## Transport Configuration
+## Configuration
 
-By default, STDIO transport is used.
+The Polygon MCP server can be configured using environment variables. See [ENV_VARIABLES.md](ENV_VARIABLES.md) for complete documentation.
 
-To configure [SSE](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#http-with-sse) or [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http), set the `MCP_TRANSPORT` environment variable.
+### Environment Variables
 
-Example:
+#### Required
+- `POLYGON_API_KEY` - Your Polygon.io API key
 
+#### Transport Configuration
+- `MCP_TRANSPORT` - Transport protocol (`stdio`, `sse`, `streamable-http`). Default: `stdio`
+
+#### Server Settings
+- `MCP_DEBUG` - Enable debug mode (`true`/`false`). Default: `false`
+- `MCP_LOG_LEVEL` - Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). Default: `INFO`
+
+#### HTTP Settings (for SSE and Streamable-HTTP)
+- `MCP_HOST` - Host/IP to bind to. Default: `127.0.0.1`
+- `MCP_PORT` - Port to bind to. Default: `8000`
+
+#### Path Settings
+- `MCP_MOUNT_PATH` - Mount path for SSE. Default: `/`
+- `MCP_SSE_PATH` - SSE endpoint path. Default: `/sse`
+- `MCP_MESSAGE_PATH` - Message endpoint for SSE. Default: `/messages/`
+- `MCP_STREAMABLE_HTTP_PATH` - Streamable HTTP endpoint. Default: `/mcp`
+
+#### Streamable HTTP Settings
+- `MCP_JSON_RESPONSE` - Return plain JSON instead of JSONRPC (`true`/`false`). Default: `false`
+- `MCP_STATELESS_HTTP` - Use stateless mode, new transport per request (`true`/`false`). Default: `false`
+
+### Examples
+
+Default STDIO transport:
+```bash
+POLYGON_API_KEY=<your_api_key_here> \
+uv run entrypoint.py
+```
+
+SSE transport with custom host/port:
+```bash
+MCP_TRANSPORT=sse \
+MCP_HOST=0.0.0.0 \
+MCP_PORT=9000 \
+POLYGON_API_KEY=<your_api_key_here> \
+uv run entrypoint.py
+```
+
+Streamable HTTP with debug logging:
 ```bash
 MCP_TRANSPORT=streamable-http \
+MCP_LOG_LEVEL=DEBUG \
+MCP_HOST=0.0.0.0 \
+POLYGON_API_KEY=<your_api_key_here> \
+uv run entrypoint.py
+```
+
+Streamable HTTP with JSON response and stateless mode:
+```bash
+MCP_TRANSPORT=streamable-http \
+MCP_JSON_RESPONSE=true \
+MCP_STATELESS_HTTP=true \
+MCP_HOST=0.0.0.0 \
 POLYGON_API_KEY=<your_api_key_here> \
 uv run entrypoint.py
 ```
@@ -146,10 +198,20 @@ Check to ensure you have the [Prerequisites](#prerequisites) installed.
 # Sync dependencies
 uv sync
 
-# Run the server
+# Run the server with default settings (stdio transport)
 POLYGON_API_KEY=your_api_key_here uv run mcp_polygon
+
+# Or run with custom configuration
+MCP_TRANSPORT=streamable-http \
+MCP_HOST=0.0.0.0 \
+MCP_PORT=8080 \
+MCP_LOG_LEVEL=DEBUG \
+POLYGON_API_KEY=your_api_key_here \
+uv run entrypoint.py
 ```
 
+See [ENV_VARIABLES.md](ENV_VARIABLES.md) for all available configuration options.
+
 <details>
   <summary>Local Dev Config for claude_desktop_config.json</summary>
 

diff --git a/docker-compose.yml b/docker-compose.yml
@@ -5,6 +5,26 @@ services:
       - .:/app
     container_name: mcp_polygon_server
     environment:
+      # Required
       - POLYGON_API_KEY=${POLYGON_API_KEY}
+      # Transport configuration
+      - MCP_TRANSPORT=${MCP_TRANSPORT:-stdio}
+      # Server settings
+      - MCP_DEBUG=${MCP_DEBUG:-false}
+      - MCP_LOG_LEVEL=${MCP_LOG_LEVEL:-INFO}
+      # HTTP settings (for SSE and Streamable-HTTP)
+      - MCP_HOST=${MCP_HOST:-127.0.0.1}
+      - MCP_PORT=${MCP_PORT:-8000}
+      # SSE-specific settings
+      - MCP_MOUNT_PATH=${MCP_MOUNT_PATH:-/}
+      - MCP_SSE_PATH=${MCP_SSE_PATH:-/sse}
+      - MCP_MESSAGE_PATH=${MCP_MESSAGE_PATH:-/messages/}
+      # Streamable-HTTP-specific settings
+      - MCP_STREAMABLE_HTTP_PATH=${MCP_STREAMABLE_HTTP_PATH:-/mcp}
+      - MCP_JSON_RESPONSE=${MCP_JSON_RESPONSE:-false}
+      - MCP_STATELESS_HTTP=${MCP_STATELESS_HTTP:-false}
     stdin_open: true
     tty: true
+    # Expose port for HTTP-based transports
+    ports:
+      - "${MCP_PORT:-8000}:${MCP_PORT:-8000}"