@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.
• Work tracking, team, and portfolio lookups.
• Team and portfolio refresh operations.
• Team and portfolio metrics.
• Feature, delivery, and forecast operations.

Runtime Configuration

Environment variables

| Variable | Required | Purpose | | --- | --- | --- | | LIGHTHOUSE_URL | Yes | Lighthouse base URL used by the MCP runtime. | | LIGHTHOUSE_API_KEY | No | API key used for outbound Lighthouse requests. | | 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. |

Set either LIGHTHOUSE_API_KEY or LIGHTHOUSE_BEARER_TOKEN when the target Lighthouse instance requires authentication.

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:

• The HTTP runtime itself reads Lighthouse credentials from its own environment. You do not need to repeat LIGHTHOUSE_API_KEY in the VS Code MCP client configuration unless you add your own gateway or proxy in front of the MCP server.
• 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.

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.