MCP onboarding

lumen is an MCP server first. One stdio command, five tools, no account. The same server binary runs wherever Node runs.

Claude Code

one-liner


      $ claude mcp add --transport stdio lumen -- npx -y @lumen-seo/cli mcp

Verify with /mcp inside Claude Code; the five lumen_* tools should be listed.

Cursor

Add the server to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "lumen": {
      "command": "npx",
      "args": ["-y", "@lumen-seo/cli", "mcp"]
    }
  }
}

Cursor also supports one-click installs via its deeplink format (cursor://anysphere.cursor-deeplink/mcp/install?… with a base64-encoded config); the JSON block above is the same config that deeplink carries.

VS Code

Use .vscode/mcp.json:

{
  "servers": {
    "lumen": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@lumen-seo/cli", "mcp"]
    }
  }
}

VS Code offers a vscode:mcp/install?{…} deeplink that pre-fills this file; the stdio command is identical either way.

Universal JSON

For any client that speaks mcpServers:

{"mcpServers":{"lumen":{"command":"npx","args":["-y","@lumen-seo/cli","mcp"]}}}

The five tools

Tool	What it does
`lumen_audit_site`	crawl a site and return the audit report (bounded, robots-safe) — local/stdio only
`lumen_page_report`	single page: PSI + CrUX when keys are configured, plus a local meta fetch
`lumen_keyword_ideas`	keyword ideas from the configured keyword provider, provenance attached
`lumen_rank_check`	best-effort SERP position for keyword + domain
`lumen_authority`	domain authority signals (Open PageRank, Tranco)

Every tool accepts an optional response_format of concise (default) or detailed. Concise is built for agents — the high-signal summary first — while detailed returns the full payload. Both carry provenance labels on every value.

Remote gateway (optional)

The repo ships a thin Cloudflare Worker that exposes the same tools over Streamable HTTP plus the REST subset (POST /mcp, GET /api/v1/page-report?url=, GET /api/v1/keyword-ideas?q=, GET /healthz). It is deployable from the free Workers tier, but nothing in lumen requires it: stdio is the primary path and the Worker is not deployed by default. BYOK keys pass per-request via headers and are never logged.

The audit stays local

lumen_audit_site is a local-only capability by design — a crawl needs CPU and politeness budgets that a shared free tier can’t offer. Over the remote gateway the tool returns a typed local-only capability error pointing at npx @lumen-seo/cli instead of silently doing less. The other tools work the same everywhere.

Keys for BYOK providers are read from the environment (LUMEN_PSI_KEY, LUMEN_CRUX_KEY, LUMEN_OPR_KEY) — see providers & BYOK.