Lighthouse can be used directly from scripts, terminals, coding agents, and MCP-enabled AI clients. The lighthouse-clients packages give you a supported way to automate Lighthouse data access and expose Lighthouse capabilities to LLMs without having to build custom glue code first.

This area is evolving quickly. If you find a client setup that works well, or a gap in the examples below, please let us know in our Slack community.

Choose the Right Option

Lighthouse currently offers three main automation entry points:

Option Best for Package
CLI Shell scripts, CI jobs, coding agents with terminal access, quick ad-hoc inspection @letpeoplework/lighthouse-cli
MCP stdio Local AI clients such as VS Code / GitHub Copilot, Claude Code, or other tools that can start a local process @letpeoplework/lighthouse-mcp-stdio
MCP HTTP Shared or hosted AI setups such as Microsoft Copilot Studio, container deployments, remote development environments, and web-based clients that need a network endpoint @letpeoplework/lighthouse-mcp-http

If your AI client can run terminal commands, the CLI is often the fastest way to automate Lighthouse. If your AI client supports MCP, use either the local stdio server or the shared HTTP server depending on your deployment model.

Packages and Downloads

The current Lighthouse automation packages are published on npm:

Lighthouse also ships ready-to-download assets from the latest lighthouse-clients release:

Think of these as two different deliverables:

  • lighthouse-mcp-stdio.mcpb is a packaged MCP server setup for clients that support MCPB
  • lighthouse-skill.zip is a packaged Lighthouse skill for clients that support importing custom skills, prompt bundles, or agent capabilities

Authentication and API Keys

If your Lighthouse instance runs without authentication, the examples on this page usually work with just the target URL.

If authentication is enabled, non-browser clients should use an API key. Create and manage those keys from System Settings > API Keys. The full authentication setup is described in Authentication.

API keys are intended for CLI usage, MCP servers, scripts, and other non-browser automation paths. Browser sign-in still uses the normal Lighthouse authentication flow.

Most client packages expect the key in the LIGHTHOUSE_API_KEY environment variable, or let you provide it during the CLI connection flow.

CLI for Scripting and Automation

Use the CLI when you want a terminal-first workflow, a scriptable JSON interface, or a straightforward way for coding agents to access Lighthouse data.

Install 

npm install -g @letpeoplework/lighthouse-cli

You can also install it globally with pnpm:

pnpm add -g @letpeoplework/lighthouse-cli

If you prefer release installers instead of npm tooling, use the latest published installer assets.

Linux and macOS:

curl -fsSL https://github.com/LetPeopleWork/lighthouse-clients/releases/latest/download/install.sh | bash

Windows:

irm https://github.com/LetPeopleWork/lighthouse-clients/releases/latest/download/install.ps1 | iex

The installer route is useful when you want the CLI available directly as lh without relying on npx or a local package install inside a project.

Connect to a Server 

lh connection connect --mode server --url https://lighthouse.example.com

If the target Lighthouse instance requires authentication, either pass the key during connect or inject it through the environment.

lh connection connect --mode server --url https://lighthouse.example.com --api-key <key>

LIGHTHOUSE_API_KEY=<key> lh connection connect --mode server --url https://lighthouse.example.com

For the local standalone desktop app, you can skip the URL and let the CLI discover Lighthouse automatically.

lh connection connect --mode standalone

Script Example

The CLI supports machine-readable output through --json, which makes it a good fit for shell pipelines and CI.

LIGHTHOUSE_API_KEY=<key> \
lh metrics team --id 1 --metrics throughput,cycleTime --json

The work in progress (lh metrics team --metrics wip or lh metrics portfolio --metrics wip) carries Lighthouse’s staleness answer for every Work Item: isStale, and in staleReasons why, such as { "kind": "TimeInState", "days": 12, "stateName": "Review" } or { "kind": "BlockedDuration", "days": 6 }. It is the same answer the Stale Items Overview shows, so a script never has to apply the thresholds itself. The MCP tool lighthouse_team_metrics_wip returns the same fields, and its summary names the stale Work Items.

Another common automation pattern is to list teams, pick an ID, and run a forecast.

LIGHTHOUSE_API_KEY=<key> lh team list --json
LIGHTHOUSE_API_KEY=<key> lh forecast manual --team-id 1 --remaining 12 --json

Read a Report

The reports of a Team or Portfolio can be read too. List them to find a report’s ID, then read it:

LIGHTHOUSE_API_KEY=<key> lh report list --team-id 1 --json
LIGHTHOUSE_API_KEY=<key> lh report get --team-id 1 --id 3 --json

Use --portfolio-id instead of --team-id for a Portfolio’s reports. The same reads are available over MCP as lighthouse_team_report_list, lighthouse_team_report_get, lighthouse_portfolio_report_list and lighthouse_portfolio_report_get.

  • Read-only. The CLI and the MCP tools never create, change or delete a report.
  • Raw values. With --json (or over MCP), you get the report as Lighthouse sends it: both windows and every value, unrounded, with no change or percentage worked out. For a Then & Now report, Then is the value frozen when the report was created, never rebuilt from today’s metrics. Without --json, lh prints a short summary: the report’s name, its Team or Portfolio and its windows.
  • Your own permissions. A reader without access to the Team or Portfolio is told so. A Lighthouse older than Reports is named as the reason, with a hint to upgrade.

To lay a report out as a dashboard or a document, with the change and the percentage exactly as the Reports tab shows them, use the Skill for Reports.

MCP for AI Clients

MCP lets AI tools call Lighthouse functionality as tools instead of relying on pasted screenshots or manually copied metrics. Lighthouse supports both a local stdio MCP server and a shared HTTP MCP server.

MCP stdio for Local Clients

Use @letpeoplework/lighthouse-mcp-stdio when your AI client can launch a local process on the same machine.

You can start it directly with npx:

npx -y @letpeoplework/lighthouse-mcp-stdio

VS Code / GitHub Copilot Example

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

{
  "servers": {
    "lighthouse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@letpeoplework/lighthouse-mcp-stdio"],
      "env": {
        "LIGHTHOUSE_URL": "https://lighthouse.example.com",
        "LIGHTHOUSE_API_KEY": "replace-me"
      }
    }
  }
}

If you are using the local Lighthouse standalone app, you can usually omit LIGHTHOUSE_URL and let the package discover the running instance.

MCPB Bundle

If your client supports .mcpb bundles, the quickest setup is the latest lighthouse-mcp-stdio.mcpb. Download the file, open it in your MCP-capable client, and provide the Lighthouse URL and optional API key when prompted.

MCP HTTP for Shared Setups

Use @letpeoplework/lighthouse-mcp-http when you want one hosted MCP endpoint that multiple users or clients can share.

Run it locally with 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

This exposes:

  • GET /health for health checks
  • POST /mcp for MCP requests

Client configuration then points to the MCP endpoint:

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

Run MCP HTTP in Docker

For containerized or remote setups, use the published Docker image:

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

Point your client to http://<host>:3000/mcp once the container is running.

Use MCP stdio for personal local setups and MCP HTTP for shared or hosted setups. If your workflow is mostly shell-based, prefer the CLI.

Microsoft Copilot Studio

Copilot Studio calls MCP servers over the network, so it needs the MCP HTTP server. The local stdio server is not an option here, because Copilot Studio cannot start a process on your machine.

Before you start, make sure you have:

  • A reachable @letpeoplework/lighthouse-mcp-http deployment served over HTTPS with a certificate Copilot Studio trusts.
  • A Lighthouse API key created under System Settings > API Keys.

Add Lighthouse as an MCP Tool

  1. Open your agent in Copilot Studio and go to Tools.
  2. Select Add a tool, then New tool, then Model Context Protocol.
  3. Fill in Server name and Server description. The agent orchestrator uses the description to decide when to call Lighthouse, so describe the capability rather than the product, for example “Flow metrics, forecasts, teams and portfolios from Lighthouse”.

  4. Set Server URL to your MCP endpoint, including the /mcp path:

     https://lighthouse.example.com/mcp
  5. Select API key as the authentication type.
  6. Set Type to Header.
  7. Enter X-Api-Key as the header name.
  8. Select Create, then Create a new connection, paste your Lighthouse API key, and select Add to agent.

The header name must be exactly X-Api-Key. The MCP HTTP server reads the caller’s key from that header and forwards it to Lighthouse, so each agent user drives Lighthouse under their own key and their own permissions. Authorization is reserved for OAuth bearer tokens and does not work with an API key.

If you build a custom connector in Power Apps instead of using the wizard, the same rule applies on the Security tab: Parameter label is only the text shown when someone creates a connection, while Parameter name is the actual HTTP header and must be X-Api-Key, with Parameter location set to Header.

URL and Transport Notes

  • The /mcp suffix is required. The MCP HTTP server only serves MCP requests on that path, and a URL without it returns 404.
  • Do not add /mcp twice. In a custom connector, the host, base URL and operation path are combined, so a base URL of /mcp together with an operation path of /mcp produces /mcp/mcp and fails.
  • Copilot Studio supports the Streamable HTTP transport only. The Lighthouse MCP HTTP server speaks Streamable HTTP, so no extra configuration is needed.
  • Tool responses are TOON-encoded rather than JSON. Copilot Studio handles this fine, but raw tool output looks different from plain JSON.

Troubleshooting

Symptom Likely cause Fix
404 when the connector is tested The server URL is missing /mcp, or /mcp was set in both the base URL and the operation path Use exactly one /mcp in the final URL
401 with a WWW-Authenticate header No credential reached the server Check that the header name is X-Api-Key and that the connection actually holds a key
406 Not Acceptable The request did not accept both application/json and text/event-stream Expected when probing by hand with curl; Copilot Studio sends the correct Accept header itself
Tools appear, but every call reports unauthorized The API key is wrong, revoked, or lacks permission for the requested data Re-create the key under System Settings > API Keys and update the connection

Lighthouse Agent Skill

The Lighthouse skill is its own deliverable, separate from the CLI and separate from the MCP server packages. It gives an LLM a ready-made kickstart for using Lighthouse effectively: when to use MCP tools, when to fall back to the CLI, how to connect to Lighthouse, and how to interpret Lighthouse flow metrics and forecasts.

You can install or inspect it here:

What the Skill Does

The skill does not replace the CLI or MCP. Instead, it teaches the LLM how to use those deliverables well.

Typical benefits include:

  • Choosing the right access path: MCP tools first, CLI as fallback
  • Guiding the model toward Lighthouse-specific commands and prompts
  • Explaining how to authenticate with API keys when needed
  • Improving the quality of flow-metrics and forecasting interpretation

How to Use It

  1. Import the lighthouse-skill.zip into a client that supports custom skills or prompt bundles.
  2. Give the client access to Lighthouse through either the CLI or an MCP server.
  3. Ask the model to use Lighthouse for a concrete task such as team metrics, forecasting, or portfolio analysis.

The skill works best together with one of the actual access mechanisms:

  • Skill + MCP stdio: best for local VS Code / GitHub Copilot or Claude-style setups where the model can call Lighthouse tools directly
  • Skill + MCP HTTP: best for shared or hosted AI environments where multiple clients connect to one MCP endpoint
  • Skill + CLI: best for terminal-capable coding agents, shell workflows, and environments where MCP is not available

In short, the skill improves the model’s Lighthouse behavior, while the CLI and MCP packages provide the real connectivity.

Example Usage Pattern

One practical setup is:

  1. Install the Lighthouse skill in the AI client.
  2. Connect Lighthouse through MCP or the CLI.
  3. Start with a task like: “Use Lighthouse to analyze the last 30 days of throughput and cycle time for team 1, then explain the delivery risks.”

This is especially useful if your client supports importing custom skills or prompt bundles and you want the model to begin with Lighthouse-specific guidance instead of a blank prompt.

Skills for Team Routines

Two more skills build on the Lighthouse skill above, each walking an assistant through one recurring Team routine. Import them the same way as the Lighthouse skill:

  • Refinement gets a Team ready for its next Refinement: whether to refine more or stop, and which Work Items are worth the session’s time. A developer can ask which Work Items wait for their vote, and vote or comment once they confirm. Try: “Are we ready for Thursday’s Refinement?”
  • Daily Flow Review opens a Team’s daily with what to decide and discuss today: Work Items that are blocked, stale, past the SLE or at risk of missing it, and WIP over its limit, each as a question for the Team, never a task for a person. A stale Work Item comes with the reason Lighthouse gave, such as “12 days in Review”, and one already listed as blocked is not listed twice. Which Work Items are stale is always Lighthouse’s own answer: against an older Lighthouse that does not say, the skill tells you so instead of working it out itself. Try: “What should Gravity discuss today?”

Downloads:

Skill for Reports

The Reports skill shows a report saved in Lighthouse to someone outside Lighthouse: as a one-page dashboard, a slide, a table or a document. It reads the report through the report tools and lays it out the way the Reports tab does, so every number, date and word is the one Lighthouse shows:

  • A header with the Team or Portfolio, the report, both windows and the day it was read.
  • The summary, then one block per metric with Then, Now, the change and the percentage, rounded as in Lighthouse.
  • A “—” stays a “—”, with its reason. Then is never rebuilt from today’s metrics.
  • The terms your Lighthouse uses, such as your own word for Work Items.
  • “Data from Lighthouse by LetPeopleWork” at the end.

If you ask for the assistant’s own take, it goes under its own heading, apart from the report’s numbers. Without a connection to Lighthouse, the skill works from an exported PDF or values you paste, and says so in the header. Today the skill knows the Then & Now report. Import it the same way as the Lighthouse skill, which it builds on. Try: “Make a one-page dashboard of Team Lightspeed’s Then & Now report for our sponsor.”

Download: lighthouse-reports-skill.zip

Example Prompts and Workflows

Once connected through CLI or MCP, common workflows look like this:

  • “List all Lighthouse teams and show me their IDs.”
  • “Run a forecast for team 1 with 12 remaining items.”
  • “Get throughput and cycle time for the last 30 days and summarize the risks.”
  • “Show portfolio metrics as raw JSON so I can use them in a script.”

For a shell-first workflow, the CLI is often enough. For natural-language, tool-driven conversations inside an AI client, prefer MCP.

Usage Data

The clients ask before they send any usage data to your Lighthouse, and nothing is sent without a yes. Today lh asks, once per Lighthouse and only in a terminal; lh config usage-data shows your answer, lh config usage-data on and off change it, and DO_NOT_TRACK always wins. Usage data never changes what a client prints or its exit code. What is sent, what is kept on your machine and how to change your mind are on the Usage Data page.

This site uses Just the Docs, a documentation theme for Jekyll.