feat: env-driven HTTP host/port and /healthz for self-hosting

[Maziak2520]

feat: env-driven HTTP host/port + /healthz for self-hosting

Problem

The README documents the HTTP transport only against Plane's hosted mcp.plane.so endpoints, and
the HTTP server has two gaps that make self-hosting it (in a container / on Cloud Run) awkward:

• Host/port are hardcoded to 0.0.0.0:8211 in __main__.py. Platforms like Cloud Run inject a
  $PORT the container must bind, so the service binds the wrong port and fails health checks. The
  Dockerfile's ENV FASTMCP_PORT=8211 is dead config (uvicorn.run ignores it).
• No health endpoint for container/orchestration probes.

What changed

• Env-driven bind: new resolve_bind() reads MCP_HOST (default 0.0.0.0) and MCP_PORT
  (default 8211). $PORT takes precedence over MCP_PORT, so Cloud Run / Heroku-style platforms work
  out of the box. Defaults match the previous hardcoded values, so nothing changes if you set nothing.
• GET /healthz → 200 {"status":"ok"}, mounted in HTTP mode for startup/liveness probes.
• Dockerfile: replaced the dead ENV FASTMCP_PORT=8211 with ENV MCP_PORT=8211.
• Docs/examples: a "Self-hosting the HTTP server" README section (env-var table, the existing OAuth
  and per-user PAT mounts, Docker/Compose, Cloud Run notes), plus .env.example and
  docker-compose.example.yml.

Backward compatibility

stdio, sse, and the existing OAuth (/http/mcp) and header-PAT (/http/api-key/mcp) mounts are
unchanged. The only behavioural change in the default path is reading MCP_HOST/MCP_PORT/$PORT
(all defaulting to the previous 0.0.0.0:8211) and adding the /healthz route. server.py is
untouched.

How it was tested

New tests/test_self_hosted_http.py (network mocked): resolve_bind() including $PORT precedence,
transport parsing, PLANE_BASE_URL / PLANE_INTERNAL_BASE_URL propagation to the client, the
header-auth gate still returning 401/403 without credentials, and /healthz returning 200. Ran
end-to-end locally in HTTP mode (healthz 200; OAuth/header mounts respond as before; $PORT precedence
confirmed).

Why it matters

Makes the HTTP server deployable as a self-hosted remote MCP service on containers / Cloud Run with no
code changes — relevant to #93 (deployment setup) and #77 (container image). Per-user identity is
preserved via the existing OAuth and PAT-header mounts.

Summary by CodeRabbit

• New Features

  • Self-hosting support for the MCP HTTP server with configurable host/port and platform $PORT precedence
  • Health-check endpoint (/healthz) and OAuth / per-user auth options for self-hosted deployments

• Documentation

  • Added self-hosting guide, .env example, Dockerfile notes, Docker Compose example, and Cloud Run deployment guidance

• Tests

  • Added tests covering bind resolution, env var precedence, auth behavior, and health endpoint

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c3eb46bf-8026-4b17-8e62-800e3bc22a4e

📥 Commits

Reviewing files that changed from the base of the PR and between 6512ef4 and 1e0c56e.

📒 Files selected for processing (2)

• docker-compose.example.yml
• tests/test_self_hosted_http.py

✅ Files skipped from review due to trivial changes (1)

• docker-compose.example.yml

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/test_self_hosted_http.py

---

📝 Walkthrough

Walkthrough

Adds a self-hosted HTTP server path: environment-driven bind resolution (PORT precedence), a /healthz endpoint, updated uvicorn startup, configuration examples (.env, Dockerfile, docker-compose), README docs, and tests covering bind logic, auth routing, and the health probe.

Changes

Self-hosted HTTP deployment for Plane MCP Server

Layer / File(s)	Summary
HTTP server runtime infrastructure plane_mcp/__main__.py	Added resolve_bind() for environment-driven host/port resolution with platform $PORT override, healthz async handler returning {"status": "ok"}, Starlette routing imports, /healthz route registration, and updated uvicorn.run() to use resolved bind address instead of hard-coded defaults.
Configuration and deployment templates .env.example, Dockerfile, docker-compose.example.yml	Provides environment variable template documenting Plane API URLs, MCP bind/port, optional path prefix, OAuth, and Redis settings. Updates Dockerfile port env var from FASTMCP_PORT to MCP_PORT with precedence comments. Adds Docker Compose service configuration with build, HTTP command, port mapping based on MCP_PORT (default 8211), env loading, and /healthz healthcheck.
Documentation and test coverage README.md, tests/test_self_hosted_http.py	Documents self-hosting instructions including run commands, OAuth/PAT mount behaviors, environment variable reference table, Docker/Cloud Run deployment with health check and $PORT handling, and updates Authentication note. Test suite validates resolve_bind() precedence (MCP_HOST/MCP_PORT → PORT), server mode parsing, PLANE_BASE_URL/PLANE_INTERNAL_BASE_URL propagation, header-auth request gating on missing workspace context, and /healthz endpoint HTTP 200 response.

Sequence Diagram

sequenceDiagram
  participant Main as main()
  participant ResolveBind as resolve_bind()
  participant Starlette as Starlette app
  participant Uvicorn as uvicorn
  participant Healthz as /healthz handler
  Main->>ResolveBind: call resolve_bind()
  ResolveBind-->>Main: returns host, port
  Main->>Starlette: register Route("/healthz", healthz)
  Main->>Uvicorn: run(app, host, port)
  Uvicorn->>Healthz: GET /healthz
  Healthz-->>Uvicorn: {"status":"ok"}

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A server wakes with a cheerful knock,
Binds to the port—no more hard-coded lock.
Health checks hum, docs and tests in tow,
Docker composes the little show,
Rabbity routing says: "Ready? Let's go!"

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.77% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: introducing environment-driven configuration for HTTP host/port (resolve_bind) and adding a /healthz health endpoint to support self-hosting scenarios.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docker-compose.example.yml`:
- Around line 16-24: Remove the hard-coded MCP_HOST/MCP_PORT values that
override env_file and make the service use Compose variable interpolation:
delete the literal MCP_HOST: 0.0.0.0 and MCP_PORT: "8211" lines, add environment
entries that read from the .env (e.g. MCP_HOST: "${MCP_HOST:-0.0.0.0}" and
MCP_PORT: "${MCP_PORT:-8211}"), change the published port mapping to use the env
var (ports: - "${MCP_PORT:-8211}:${MCP_PORT:-8211}") and update the healthcheck
test to reference the same interpolated port (test: ["CMD", "curl", "-fsS",
"http://localhost:${MCP_PORT:-8211}/healthz"]) so env_file, ports and
healthcheck all honor .env settings.

In `@tests/test_self_hosted_http.py`:
- Around line 79-83: The test
test_header_app_rejects_request_without_workspace_slug is not exercising the
PAT-specific branch because no Authorization header is sent; modify the
TestClient POST to include a Bearer token (e.g., set an Authorization: Bearer
<token> header) while deliberately omitting the X-Workspace-Slug header so the
logic in plane_mcp/auth/plane_header_auth_provider.py that checks for the
workspace slug (lines handling x-workspace-slug) is actually reached and the
response asserts 401/403 as intended.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 80f25845-4140-4351-a90f-28d505e4b280

📥 Commits

Reviewing files that changed from the base of the PR and between 369889e and 6512ef4.

📒 Files selected for processing (6)

• .env.example
• Dockerfile
• README.md
• docker-compose.example.yml
• plane_mcp/__main__.py
• tests/test_self_hosted_http.py

[Maziak2520]

Thanks @coderabbitai — both addressed in 1e0c56e:

1. docker-compose.example.yml — ports, MCP_HOST/MCP_PORT, and the healthcheck now use ${MCP_PORT:-8211} / ${MCP_HOST:-0.0.0.0} interpolation, so editing .env actually changes the bind and probe target. Verified with docker compose config (e.g. MCP_PORT=9000 → published/target 9000).
2. test_header_app_rejects_request_without_workspace_slug — now sends Authorization: Bearer dummy-pat while omitting X-Workspace-slug, so the PAT-specific workspace-slug gate is exercised rather than generic unauthenticated handling.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@Maziak2520 Thanks for the thorough follow-up! Both fixes look exactly right:

1. docker-compose.example.yml — Using ${MCP_PORT:-8211} / ${MCP_HOST:-0.0.0.0} throughout (published port, target port, and healthcheck URL) ensures a single .env edit propagates consistently everywhere. The docker compose config verification confirms it works end-to-end.
2. test_header_app_rejects_request_without_workspace_slug — Sending the Authorization: Bearer dummy-pat header while deliberately omitting X-Workspace-slug now correctly targets the PAT-specific gate rather than falling through to generic unauthenticated handling.

Both concerns are fully addressed. 🐇✨

---

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!