docs: ensure consistent PORT and HOST_PORT documentation across codebase and docs

.env.example

@@ -17,9 +17,16 @@ OPENPROJECT_HOST__NAME=localhost:8080
 OPENPROJECT_HTTPS=false
 SECRET_KEY_BASE=openproject-secret-key-base-for-local-testing-at-least-64-characters-long
 
-# MCP Server Client Configuration
+# MCP Server Client Configuration (Stdio Mode)
 # Once the container is running and seeded via scripts/seed.sh,
 # OPENPROJECT_API_KEY will be automatically written to .env.test
 OPENPROJECT_BASE_URL=http://localhost:8080
 OPENPROJECT_API_KEY=
 OPENPROJECT_READ_ONLY=false
+
+# Hosted Remote MCP Server Configuration (HTTP/SSE Mode)
+# When PORT (or HOST_PORT) is set, openproject-mcp runs as an HTTP/SSE server.
+# In HTTP mode, connecting clients supply their own API keys, so OPENPROJECT_API_KEY is optional.
+# PORT=3000
+# HOST=0.0.0.0
+# HOST_PORT=3000

README.md

@@ -418,6 +418,7 @@ The MCP server accepts configuration through environment variables, CLI argument
 | `OPENPROJECT_API_KEY` | Personal API token (required in stdio mode; supplied per-client in HTTP mode) | - |
 | `OPENPROJECT_READ_ONLY` | Run server in read-only mode (`true` / `false` or `--read-only`) | `false` |
 | `PORT` | HTTP server port when running hosted MCP server, or web port for local dev stack | `3000` (MCP) / `8080` (test stack) |
+| `HOST_PORT` | Optional environment fallback for `PORT`, and host-side port in `docker-compose.server.yml` | `3000` |
 | `HOST` | Bind host for hosted HTTP server | `0.0.0.0` |
 | `TAG` | OpenProject container image tag (local test stack) | `17-slim` |
 | `POSTGRES_VERSION` | PostgreSQL container image tag (local test stack) | `17` |

docs/ARCHITECTURE.md

@@ -75,9 +75,11 @@ Domain services map MCP tool calls to concrete business logic and OpenProject AP
 ### 2.4. Configuration & Environment Layer
 - Parses and validates configuration at startup:
   - `OPENPROJECT_BASE_URL`: Base URL of the OpenProject instance (e.g., `https://openproject.example.com`).
-  - `OPENPROJECT_API_KEY`: User API key generated in OpenProject under "My Account > Access tokens".
+  - `OPENPROJECT_API_KEY`: User API key generated in OpenProject under "My Account > Access tokens" (required in stdio mode; optional in HTTP/SSE mode).
   - `OPENPROJECT_READ_ONLY`: Boolean flag (`true` / `false`, default: `false`). Can also be set via `--read-only` CLI argument.
-- Fails fast with actionable setup advice if required credentials are missing or invalid.
+  - `PORT`: HTTP server listening port (e.g. `3000` or `--port <num>`). When set, activates HTTP/SSE remote transport. Supports `HOST_PORT` as an environment variable fallback.
+  - `HOST`: Server bind address (or `--host <addr>`, default: `0.0.0.0`).
+- Fails fast with actionable setup advice if required credentials are missing or invalid in stdio mode.
 
 ### 2.5. Read-Only Execution Mode
 The server supports a dedicated read-only operating mode designed for auditing, reporting, and exploratory agent workflows:

docs/DECISIONS.md

@@ -376,7 +376,7 @@ Accepted
 
 Key requirements for hosted operation:
 1. **Multi-Tenant Credential Scoping**: A single server process connects to a shared OpenProject base URL (`OPENPROJECT_BASE_URL`), but every connecting user/agent must use their own personal OpenProject API token. User credentials must never bleed across sessions or be retained in global mutable memory.
-2. **Dual-Transport Entrypoint**: The server CLI must support both local stdio execution and hosted HTTP/SSE execution via configuration (`PORT` / `--port`).
+2. **Dual-Transport Entrypoint**: The server CLI must support both local stdio execution and hosted HTTP/SSE execution via configuration (`PORT`, `HOST_PORT` fallback, or `--port`).
 3. **Flexible Authentication**: Clients must be able to authenticate via standard headers (`Authorization: Bearer <key>`, `X-OpenProject-Api-Key: <key>`) or query parameters (`?apiKey=<key>`) for SSE-compatible desktop and web clients.
 4. **Health & Lifecycle Management**: Provide standardized `/health` endpoints and clean session eviction on client disconnect to prevent memory leaks.
 

src/config/index.ts

@@ -21,7 +21,8 @@ export const configSchema = z
     if (data.port === undefined && (!data.apiKey || data.apiKey.trim().length === 0)) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: "OPENPROJECT_API_KEY is required in stdio mode (when port is not set)",
+        message:
+          "OPENPROJECT_API_KEY is required in stdio mode (set PORT, HOST_PORT, or --port to run as an HTTP server)",
         path: ["apiKey"],
       });
     }