@letpeoplework/lighthouse-mcp-http

Streamable HTTP MCP runtime for Lighthouse.

Use this package when you want to host Lighthouse as a shared MCP endpoint instead of starting a local stdio process per client.

What It Exposes

The HTTP runtime exposes Lighthouse as MCP tools for:

• Health and version checks. lighthouse_health_check and lighthouse_version_get keep their facts block (connectivity: success, version: v26.10.3.6) and add a second block, summary: Lighthouse is reachable. or summary: Lighthouse v26.10.3.6, as the footer shows it.
• Work tracking, team, and portfolio lookups. lighthouse_worktracking_list keeps its facts block and adds a second block counting the connections in the instance's words (summary: 3 Work Tracking Systems); lighthouse_worktracking_get carries a summary naming the connection and its type, never an option's value. lighthouse_blackout_list counts the recurring blackout rules the same way (summary: 2 recurring blackout rules). lighthouse_team_list and lighthouse_portfolio_list keep their facts block and add a second block counting them (summary: 7 Teams); lighthouse_team_get and lighthouse_portfolio_get carry the page's heading and settings as summary, as lh team get and lh portfolio get print them.
• Team and portfolio refresh operations. lighthouse_team_refresh and lighthouse_portfolio_refresh keep their facts block (team refreshed: 3) and add the line lh confirms with as a second block (summary: Refresh queued: Team [id: 3]. Lighthouse updates it in the background.). The recurring blackout tools (lighthouse_blackout_create, _update, _delete) do the same, the rule's own summary field left as Lighthouse sent it.
• Team and portfolio metrics. Each per-metric tool (Throughput, the Cycle Time and Work Item Age percentiles, Work Item Age, Total Work Item Age, the blocked history, the percentiles over time, the process limits and Time in State) also states its answer as lh metrics --metrics <name> heads it: the heading and the sentence. Time in State's drill-down into one state states the heading and the title above its Work Items; the list of Work Items to pick from carries no summary.
• What a Team has in progress, its SLE Risk, and Process Behaviour Charts. lighthouse_team_metrics_wip lists each Work Item in progress today with its age, state, whether it is Blocked and since when, and its link, beside a summary counting them against the System WIP Limit and naming how many are Blocked, or saying that no System WIP Limit is set, that Lighthouse does not say which Work Items are Blocked, or that nothing is in progress. lighthouse_team_metrics_sleRisk returns Lighthouse's own SLE Risk for each Work Item in progress unchanged, beside a summary in the words lh metrics team --metrics sleRisk --pretty uses: how many are at risk of missing the SLE, counted from the web's 70% line, then every Work Item highest risk first. It needs a Lighthouse newer than v26.9.19.10; an older one's refusal comes back as the upgrade it asks for. lighthouse_team_metrics_processBehaviorChart and lighthouse_portfolio_metrics_processBehaviorChart return one Process Behaviour Chart, named with metricType (Throughput, WorkItemAge, Wip, CycleTime, Arrivals, and FeatureSize for Portfolios only), unchanged, beside a summary naming each signal with the days it fired, or saying there are no signals, that no baseline is set, or why Lighthouse could not compute the chart.
• Feature, delivery, and forecast operations. lighthouse_feature_get keeps its facts block and adds a second block counting the Features (summary: 3 Features); lighthouse_feature_workitems adds the heading lh feature workitems prints (summary: OE-002 Deep-sea camera stream · 3 Work Items), naming the Feature by its id when its name cannot be read. lighthouse_delivery_list keeps its facts block and adds a second block counting the Deliveries (summary: 4 Deliveries); lighthouse_delivery_metrics states the Delivery and its Delivery Date as lh delivery metrics heads them, in a second block beside the day-by-day rows or as the summary field of the detail: "epics" payload. The forecast tools (lighthouse_forecast_manual, lighthouse_forecast_backtest) also return a summary stating the answer as the web does: the heading and likelihood sentence, or the backtest's heading, period and actual Throughput.
• A Team's refinement need (lighthouse_team_refinement_get): how many Work Items to refine before the next Refinement, with the sentence the web page states as summary.
• Refinement votes: lighthouse_team_refinement_vote, lighthouse_team_refinement_comment and lighthouse_team_refinement_voteTakeBack record the caller's own vote, comment or take-back on a Work Item in refinement, as their own credential. They need a Lighthouse with sign-in: this server is shared and cannot tell one person from another without it, so on a Lighthouse without sign-in it refuses all three and points to the web page, lh or a local stdio server. With sign-in, each request must carry the caller's own credential (X-Api-Key or Authorization: Bearer): a request that would fall back to the server's LIGHTHOUSE_API_KEY is refused, so nobody votes as the operator.

Runtime Configuration

Environment variables

| Variable | Required | Purpose | | --- | --- | --- | | LIGHTHOUSE_URL | Yes | Lighthouse base URL used by the MCP runtime. | | LIGHTHOUSE_API_KEY | No | Fallback API key for callers that send no credential of their own. | | LIGHTHOUSE_BEARER_TOKEN | No | Bearer token used for outbound Lighthouse requests. | | HOST | No | Bind host. Defaults to 127.0.0.1. | | PORT | No | Bind port. Defaults to 3333. | | LIGHTHOUSE_USAGE_DATA | No | on sends usage data for everyone this server serves. Off when unset. See Usage data. |

Set either LIGHTHOUSE_API_KEY or LIGHTHOUSE_BEARER_TOKEN when the target Lighthouse instance requires authentication and callers do not bring their own credential.

Caller credentials

A credential on the inbound MCP request takes precedence over the configured fallback, so each caller drives Lighthouse as themselves instead of sharing one baked key:

| Inbound header | Used as | | --- | --- | | X-Api-Key: <key> | Lighthouse API key | | Authorization: Bearer <token> | Lighthouse bearer token |

When neither header is present, the server falls back to LIGHTHOUSE_API_KEY / LIGHTHOUSE_BEARER_TOKEN. Send API keys in X-Api-Key — an API key placed in Authorization is treated as a bearer token and rejected.

Run Locally

The simplest local startup flow uses npx:

LIGHTHOUSE_URL=https://lighthouse.example.com \
LIGHTHOUSE_API_KEY=replace-me \
HOST=127.0.0.1 \
PORT=3333 \
npx -y @letpeoplework/lighthouse-mcp-http

If startup succeeds, the process writes a banner like:

Lighthouse MCP HTTP server running at http://127.0.0.1:3333

The runtime exposes:

• GET /health for health checks.
• POST /mcp for MCP JSON-RPC requests.

Quick health check:

curl http://127.0.0.1:3333/health

VS Code / GitHub Copilot

Add the server URL to .vscode/mcp.json in your workspace or to your user MCP configuration:

{
  "servers": {
    "lighthouse": {
      "type": "http",
      "url": "http://127.0.0.1:3333/mcp"
    }
  }
}

Notes:

• With no credential in the client configuration, the runtime falls back to the credentials in its own environment. To have VS Code call Lighthouse under a specific key instead, send it as an X-Api-Key request header.
• After saving mcp.json, start or restart the server from the MCP commands in VS Code.

Claude Code

Add the server as a remote HTTP MCP endpoint:

claude mcp add --transport http --scope user \
  lighthouse http://127.0.0.1:3333/mcp

If your deployment sits behind an authenticated reverse proxy, add the required request headers there:

claude mcp add --transport http --scope user \
  --header "Authorization: Bearer replace-me" \
  lighthouse https://mcp.example.com/mcp

You can also commit a project-scoped .mcp.json file for Claude Code:

{
  "mcpServers": {
    "lighthouse": {
      "type": "http",
      "url": "http://127.0.0.1:3333/mcp"
    }
  }
}

After adding the server, use /mcp in Claude Code to verify that it is connected.

Docker Use Case

The HTTP package is the right fit when you want to run Lighthouse MCP as a small shared service for a team, a remote development environment, or a hosted AI setup where local stdio processes are inconvenient.

Run the published container image from GHCR:

docker run --rm \
  -p 3000:3000 \
  -e HOST=0.0.0.0 \
  -e PORT=3000 \
  -e LIGHTHOUSE_URL=https://lighthouse.example.com \
  -e LIGHTHOUSE_API_KEY=replace-me \
  ghcr.io/letpeoplework/lighthouse-clients/mcp-http:latest

Important details:

• Set HOST=0.0.0.0 so the container is reachable outside the container namespace.
• Set PORT=3000 to match the container's exposed port.
• Point clients at http://<host>:3000/mcp.

Example docker-compose.yml service:

services:
  lighthouse-mcp:
    image: ghcr.io/letpeoplework/lighthouse-clients/mcp-http:latest
    ports:
      - "3000:3000"
    environment:
      HOST: 0.0.0.0
      PORT: 3000
      LIGHTHOUSE_URL: https://lighthouse.example.com
      LIGHTHOUSE_API_KEY: replace-me

Health check the running container:

curl http://127.0.0.1:3000/health

When to Use HTTP vs stdio

Use @letpeoplework/lighthouse-mcp-http when you want one hosted MCP endpoint that many clients can connect to.

Use @letpeoplework/lighthouse-mcp-stdio when each developer should run Lighthouse tools locally inside their own MCP client process.

Runtime Behavior

Tool response format

All MCP tool responses are serialized using TOON instead of plain JSON. TOON is a structured text format designed for LLM consumption. MCP clients that display raw tool results will see TOON-encoded output.

A tool that carries a summary states its answer there as the web does, in the instance's terminology. An object answer carries it as a summary field beside the facts. A list answer keeps its facts block exactly as before and carries the summary in a second text block, summary: …. Every other field is the facts, unchanged; when the tool does not recognise the answer's shape it adds no summary.

Usage data

This server sends usage data only when whoever runs it sets LIGHTHOUSE_USAGE_DATA=on. Nobody it serves is asked: the operator decides for all of them.

• on, in any case, switches it on. Unset, empty or off keeps it off. Any other value keeps it off too, and the server still starts, with one warning naming the values it takes.
• DO_NOT_TRACK wins over on: the server sends nothing.
• At start-up the server prints Usage data: on (LIGHTHOUSE_USAGE_DATA) or Usage data: off.
• Switched on, it reports refreshing a Team, refreshing a Portfolio and running a manual forecast, each labelled as coming from MCP. Callers get the same answers either way.
• The whole process counts as one: it requests one grant on the first call worth counting and holds it in memory only, so a restart counts as a new one. Nothing is written to disk.
• No API key or bearer token travels with usage data: neither LIGHTHOUSE_API_KEY nor a caller's own credential.
• When the Lighthouse's administrator has switched usage data off, or the Lighthouse is too old to take it from MCP, the server sends nothing and looks again at most once an hour, so switching it back on takes effect without a restart.
• The Lighthouse Helm chart has no value for this yet, so a server deployed with the chart stays off.

TLS certificate validation

All outbound HTTPS requests to Lighthouse skip TLS certificate validation. This is intentional and hard-enforced so the server works with self-hosted Lighthouse instances that use self-signed certificates. There is no option to enable strict TLS validation.