Connect your AI tool to Lantern¶

Lantern speaks MCP (Model Context Protocol) to AI tools. This page walks through installing the Lantern MCP server into Claude Code, Cursor, Claude Desktop, and any other MCP host — in about 5 minutes.

Prerequisites: you have a Lantern account (sign in with your email + password works) and you know your Lantern URL (e.g. https://lantern.evgeniy.online). You do not need to mint a token by hand — the shim logs in with your email + password on first run and mints one for you (see §0).

0. The shim in 30 seconds¶

Lantern's MCP server is a small Node program (lantern-mcp). It runs locally on your machine as a child process of your AI tool, and proxies the tool calls to your company's Lantern instance over HTTPS.

┌──────────────┐    stdio (MCP)    ┌──────────────┐    HTTPS    ┌──────────────┐
│  Claude Code │ ←──────────────→  │  lantern-mcp │ ←────────→  │   Lantern    │
│  Cursor /    │                   │  (Node shim) │             │   server     │
│  Desktop /…  │                   │              │             │              │
└──────────────┘                   └──────────────┘             └──────────────┘

Login once, never paste a token. On first startup the shim:

logs in with your email + password (POST /api/v1/auth/login),
mints a never-expire personal token (POST /api/v1/auth/cli-token),
stores it at ~/.lantern/credentials (JSON, mode 0600),
uses it as the Authorization: Bearer on every call.

Later startups read the stored token straight from ~/.lantern/credentials — no login round-trip. The password is used only at startup to mint the token and is never written to disk or logged.

You'll point your AI tool at node <path-to>/lantern-mcp/server/index.js and pass LANTERN_URL + LANTERN_EMAIL + LANTERN_PASSWORD as env vars.

1. Get the shim (one-time, per machine)¶

There is one download for everyone — the self-contained bundle:

→ https://lantern.evgeniy.online/wiki/downloads/lantern-mcp.mcpb

It already contains the server and its node_modules — no git, no npm install, nothing to build. What you do with it depends on your tool:

Claude DesktopClaude Code / Cursor / Codex / other

Don't unzip it. Double-click the .mcpb and Claude Desktop installs it as an extension. Skip to §4.

The .mcpb is just a ZIP. Unzip it to a folder you'll keep, e.g.:

# macOS / Linux
mkdir -p ~/lantern-mcp && unzip ~/Downloads/lantern-mcp.mcpb -d ~/lantern-mcp

# Windows PowerShell
Expand-Archive $HOME\Downloads\lantern-mcp.mcpb -DestinationPath $HOME\lantern-mcp

The server entrypoint is then:

~/lantern-mcp/server/index.js

Use the absolute path to that file in the configs below. The only requirement on your machine is Node.js ≥ 20 (node --version) — the bundle carries its own dependencies.

Developers working on Lantern itself can instead run the shim straight from a repo checkout (cd clients/lantern-mcp && npm ci) and point at clients/lantern-mcp/server/index.js. End users do not need the repo.

2. Claude Code (CLI)¶

Option A — `claude mcp add` (one command)¶

claude mcp add lantern \
  -e LANTERN_URL=https://lantern.evgeniy.online \
  -e LANTERN_EMAIL=[email protected] \
  -e LANTERN_PASSWORD=your-password \
  -- node /absolute/path/to/lantern-mcp/server/index.js

Add -s user to share the server across all your projects, or -s project to write it into the repo's .mcp.json (committed — keep secrets in env vars, see below). Default is local (this machine only).
Verify with /mcp inside a Claude Code session — lantern should appear with its toolset.

First run logs in and writes ~/.lantern/credentials (0600); later runs reuse the stored token.

Option B — project `.mcp.json`¶

Drop a .mcp.json in your project root (Claude Code expands ${VAR} from your shell environment, so secrets stay out of the committed file):

{
  "mcpServers": {
    "lantern": {
      "command": "node",
      "args": ["/absolute/path/to/lantern-mcp/server/index.js"],
      "env": {
        "LANTERN_URL": "https://lantern.evgeniy.online",
        "LANTERN_EMAIL": "${LANTERN_EMAIL}",
        "LANTERN_PASSWORD": "${LANTERN_PASSWORD}",
        "CONFLUENCE_PAT": "${CONFLUENCE_PAT}",
        "JIRA_PAT": "${JIRA_PAT}"
      }
    }
  }
}

Then export the secrets in your shell rc:

# ~/.zshrc or ~/.bashrc
export LANTERN_EMAIL='[email protected]'
export LANTERN_PASSWORD='your-password'
# optional, for write-back + per-user ACL (see §6):
export CONFLUENCE_PAT='...'
export JIRA_PAT='...'

3. Cursor¶

Settings → MCP → Add new MCP Server, or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in a project root:

{
  "mcpServers": {
    "lantern": {
      "command": "node",
      "args": ["/absolute/path/to/lantern-mcp/server/index.js"],
      "env": {
        "LANTERN_URL": "https://lantern.evgeniy.online",
        "LANTERN_EMAIL": "[email protected]",
        "LANTERN_PASSWORD": "your-password"
      }
    }
  }
}

Reload Cursor (Settings → MCP → toggle lantern off/on).

4. Claude Desktop — `.mcpb` bundle (recommended)¶

Claude Desktop supports one-click extension bundles — no clone, no JSON, no node on PATH.

Download the bundle: https://lantern.evgeniy.online/wiki/downloads/lantern-mcp.mcpb
Quit Claude Desktop completely.
Double-click lantern-mcp.mcpb (on macOS/Windows with Claude Desktop registered as the handler it opens directly), or drag the file into Claude Desktop → Settings → Extensions.
Claude prompts for the config values in its settings form (there is no in-extension browser/login button — login is plain email + password fields, which is why there's no OAuth redirect):
Lantern URL — https://lantern.evgeniy.online
Email + Password — the recommended login; the extension mints and stores the token locally, you never paste one
Confluence PAT / Jira PAT (optional) — for per-user ACL + write-back (see §6)
Bearer token (advanced, optional) — paste an existing Lantern token to skip email/password (see §7)
Read-only — leave on (default) to start safe; turn off when you need write tools
Claude restarts. Open Settings → Extensions — lantern should show running.

The .mcpb bundle stores secrets in the OS keychain, not plaintext. To change a value later, remove the extension and re-add the bundle — Desktop reads user_config secrets at install time. (The minted Lantern token also lives in ~/.lantern/credentials; delete that file to force a fresh login.)

5. Any other MCP host (generic)¶

Every host that speaks stdio MCP takes the same command + args + env shape. Drop this block into the host's MCP config (mcpServers map):

{
  "mcpServers": {
    "lantern": {
      "command": "node",
      "args": ["/absolute/path/to/lantern-mcp/server/index.js"],
      "env": {
        "LANTERN_URL": "https://lantern.evgeniy.online",
        "LANTERN_EMAIL": "[email protected]",
        "LANTERN_PASSWORD": "your-password",
        "READ_ONLY": "true"
      }
    }
  }
}

Hosts that use TOML (e.g. Codex CLI, ~/.codex/config.toml) take the equivalent table:

[mcp_servers.lantern]
command = "node"
args    = ["/absolute/path/to/lantern-mcp/server/index.js"]

[mcp_servers.lantern.env]
LANTERN_URL      = "https://lantern.evgeniy.online"
LANTERN_EMAIL    = "[email protected]"
LANTERN_PASSWORD = "your-password"
READ_ONLY        = "true"

Restart the host and confirm lantern appears in its tool list.

5c. Streamable HTTP transport (for the MCPJungle gateway)¶

Everything above (§2–§5) uses the stdio transport: your AI tool spawns the shim as a child process. That stays the default and the recommended path for Claude Code, Cursor, Codex, and the .mcpb bundle.

If you run a MCP gateway instead — MCPJungle or LibreChat — the gateway reaches MCP servers over streamable HTTP, not stdio. The shim supports that via MCP_TRANSPORT=http.

1. Build the HTTP image:

cd clients/lantern-mcp
npm run docker:build        # → docker build -t lantern-mcp -f Dockerfile .

2. Run it with a client→shim key (SHIM_API_KEY) and the lantern backend credentials the shim forwards on every REST call:

docker run -d --name lantern-mcp \
  -p 8768:8768 \
  -e SHIM_API_KEY=<pick-a-shared-secret> \
  -e LANTERN_URL=https://lantern.evgeniy.online \
  -e LANTERN_BEARER=${LANTERN_BEARER} \
  lantern-mcp

The endpoint is then http://<host>:8768/mcp, served stateless (one POST /mcp per JSON-RPC request; GET/DELETE return 405). Tool schemas are generated once at startup, identical to the stdio tool surface — the gateway sees the same lantern tool set your local agent does.

Variable	Default	Purpose
`MCP_TRANSPORT`	`stdio`	Set `http` (the Dockerfile already sets it).
`SHIM_HOST` / `SHIM_PORT`	`0.0.0.0` / `8768`	Bind in the image.
`SHIM_API_KEY`	(unset)	Bearer the gateway must send as `Authorization: Bearer …`. Set it — without it the shim is an open relay. Separate from `LANTERN_BEARER` (the shim→lantern backend token).
`SHIM_CORS_ORIGINS`	(unset)	Optional CSV of browser origins if the gateway is browser-side.

3. Point the gateway at the shim as a streamable_http upstream:

# MCPJungle server registration (abbreviated)
transport: streamable_http
url: http://<host>:8768/mcp
headers:
  Authorization: "Bearer <pick-a-shared-secret>"

The gateway then proxies your AI clients to lantern over HTTP; each client gets the curated tool set and the same per-user ACL as the stdio path.

The stdio default and the .mcpb bundle are unchanged — HTTP mode is purely additive. manifest.json stays stdio-only.

5b. CLI alternative: the `lantern` command¶

If your AI tool can run shell commands (Claude Code, Codex), you can skip the MCP server entirely and use the lantern CLI — a single binary that talks to the same Lantern API. It is lighter on the model's context (the agent discovers commands on demand instead of loading every tool schema up front) and composes with the shell (lantern search … | jq). It exposes the identical command set and the same per-user ACL as the MCP server — pick whichever fits.

1. Get the binary for your OS — one self-contained file, no Node needed:

OS	Download
macOS (Apple Silicon)	`lantern-darwin-arm64`
macOS (Intel)	`lantern-darwin-x64`
Linux (x64)	`lantern-linux-x64`
Windows (x64)	`lantern-windows-x64.exe`

Put it on your PATH and make it runnable:

# macOS / Linux
mkdir -p ~/.local/bin
curl -fSL https://lantern.evgeniy.online/wiki/downloads/lantern-linux-x64 -o ~/.local/bin/lantern
chmod +x ~/.local/bin/lantern
# macOS only, clear the quarantine flag on first download:
# xattr -d com.apple.quarantine ~/.local/bin/lantern 2>/dev/null || true

Developers can also build it from a repo checkout instead of downloading: cd clients/lantern-mcp && npm ci && npm run build:cli → dist/lantern.

2. Log in once.

LANTERN_URL=https://lantern.evgeniy.online LANTERN_EMAIL=[email protected] \
  LANTERN_PASSWORD=your-password lantern list

This logs in and caches your token and the URL at ~/.lantern/credentials (mode 0600), so afterwards bare lantern <command> just works — no env vars.

3. Discover + use.

lantern list --json                  # every command + its JSON-Schema params
lantern search "marketplace pricing"
lantern fetch confluence-dc:12345
lantern read_issue CMP-559

Output is JSON on stdout. An agent runs lantern list --json once to learn the whole surface, then calls commands directly.

4. Write-back. Same gating as the MCP server: set READ_ONLY=false and provide your CONFLUENCE_PAT / JIRA_PAT in the environment (see §6). Writes are attributed to you upstream, exactly as through the shim.

A repo-local skill (.claude/skills/lantern-cli) teaches agents to use the CLI.

6. Adding write access + per-user ACL (Atlassian PAT)¶

You can connect your PAT in the web UI instead. The Tokens page (/tokens → "Atlassian access") and the "Sign in with Atlassian" option on /login both submit your PAT to the same place. Because the resulting ACL is stored server-side per account, connecting it once (web or shim) is enough — your agent session, signed in as the same account, inherits it. (The shim config below still forwards the PAT as request headers, which is what enables write tools.)

Read-only is enough for most queries. Supplying an Atlassian Personal Access Token does two things:

Per-user ACL — the shim submits the PAT once to Lantern (/auth/atlassian-pat), and Lantern discovers exactly which Confluence spaces / Jira projects you can read. Your search results are then filtered to what you personally can see upstream.
Write-back — the same PAT is forwarded as X-Confluence-PAT / X-Jira-PAT so the agent can edit pages, comment on issues, and transition workflows under your name (with READ_ONLY=false).

Don't confuse the two tokens. Your Lantern login (email + password) authenticates you to Lantern and mints the bearer. The Atlassian PAT is a separate token, generated inside Confluence / Jira, that Lantern forwards so reads are ACL-scoped and writes are attributed to you upstream. Lantern never uses a server-side service PAT for your access.

6.1 Generate the PATs¶

Confluence DC: open https://confluence.comfy.ua/plugins/personalaccesstokens/usertokens.action (or avatar top-right → Settings/Profile → Personal Access Tokens) → Create token. Name: lantern-mcp. Expiry: 90 days. Copy it (shown once).
Jira DC: open https://jira.comfy.ua/secure/ViewProfile.jspa → left menu Personal Access Tokens → Create token. Same name + expiry.

Store them in your password manager. Never paste a PAT into a committed config file — use env-var interpolation (${CONFLUENCE_PAT}) or the keychain-backed Desktop form.

6.2 Add PATs to the shim config¶

Claude Code / Cursor / generic — add CONFLUENCE_PAT / JIRA_PAT to the env block, and set READ_ONLY to false to expose write tools.
Claude Desktop — fill the Confluence PAT / Jira PAT form fields and toggle Read-only off.

6.3 Reconnect¶

PATs are picked up only after the MCP session restarts:

Claude Desktop: quit + reopen (or remove + re-add the bundle).
Claude Code: new session, or /mcp → reconnect lantern.
Cursor: Settings → MCP → toggle lantern off/on.

6.4 Verify¶

Ask the agent something that definitely exists in Confluence or Jira. The Lantern audit log will show identity_method=bearer+pat (with a non-reversible PAT fingerprint). If you only see bearer — the env vars didn't reach the shim; double-check the config.

Write tools also require editor mode server-side. If READ_ONLY=false but no write tools appear, your Lantern instance has editor mode disabled — ask your admin.

7. Advanced: `LANTERN_BEARER` override¶

If you already have a Lantern token (lnt_pat_…, minted on the Tokens page or by a prior login) and want to skip the email + password flow, set LANTERN_BEARER instead. It takes precedence over both email/password and the stored ~/.lantern/credentials, and never touches disk or the network:

"env": {
  "LANTERN_URL": "https://lantern.evgeniy.online",
  "LANTERN_BEARER": "${LANTERN_BEARER}"
}

This is the legacy path — most users should prefer email + password so the token is minted and rotated for them.

8. Verify it works¶

In any AI tool, ask:

"What do we have in Confluence about marketplace pricing?"

The agent should call search (or context_pack) and return ranked results with breadcrumbs and Confluence URLs. If you get an error, see Troubleshooting below.

9. ⚠️ I see no results — why?¶

You only see a document if it is both:

indexed in Lantern — the relevant Confluence space / Jira project is in your instance's CONFLUENCE_SPACES / JIRA_PROJECTS ingest scope, and
visible to your own Atlassian PAT — your upstream permissions allow you to read it.

So an empty or thin search is usually not a shim bug:

Nothing comes back at all → either you haven't supplied your Atlassian PAT (so Lantern can't scope your ACL — see §6), or the space/project you're asking about was never indexed. The fix for the latter is on the admin: add the space/project to CONFLUENCE_SPACES / JIRA_PROJECTS and re-ingest.
You see less than a teammate → expected. Results are filtered to your upstream permissions. Lantern never shows you a doc your Atlassian account can't read.

If a doc you can open in Confluence/Jira is missing from search, it's an indexing-scope question for your admin, not a permissions one.

10. Troubleshooting¶

The shim logs to stderr with a [lantern-mcp] prefix; watch your AI tool's MCP/stderr log.

Symptom	Cause / fix
`401` on every tool call	No token resolved or it's wrong. Check stderr for `auth resolved via …` vs `WARNING: no credentials resolved`. Fix email/password (or delete `~/.lantern/credentials` to force a fresh login).
`login failed: …`	Bad email/password, or server down. Password is never logged. Correct it and restart.
`Connection timed out`	Not on the company network. Check `curl <url>/healthz`.
`lantern` shows but toolset empty	Shim can't fetch `<url>/openapi.json`. Check `LANTERN_URL`, no `/mcp` suffix.
`spawn node ENOENT`	`node` not in `PATH`. Use the absolute path (`which node`).
No write tools with `READ_ONLY=false`	Editor mode disabled server-side — ask admin. Or PAT missing (§6).
`caller_pat_missing` / `403` on a write	Bearer-only — add `CONFLUENCE_PAT` / `JIRA_PAT` (§6).
`expected_version` mismatch	Page changed between read and write — agent re-reads, retries.
`429 too many writes`	Server rate-limits writes per process. Slow down.
`403` from Atlassian on write	Your PAT lacks permissions for that page/issue. Fix in Atlassian; Lantern doesn't bypass.
Empty / thin search results	See §9 — indexing scope + ACL.
Data is stale	`lantern-sync` polls periodically; webhooks fire instantly. If both are broken, ping the admin.

11. What the agent sees¶

The shim exposes read tools by default (and write tools only when READ_ONLY=false and the server has editor mode enabled):

read: search, fetch, find_similar, list_recent, context_pack, list_tags, graph_neighbors, graph_subtree, graph_referenced_by, graph_find_path
write: replace_section_*, comment_on_*, create_page, transition_issue, update_issue_field, create_issue, … (require your PAT and READ_ONLY=false)

Tool	One-line example
`search`	"Find our docs on marketplace pricing."
`fetch`	"Open `confluence:12345` in full."
`find_similar`	"What else is like `jira:CMP-559`?"
`list_recent`	"What changed in the last few days?"
`context_pack`	"Give me everything on merchant onboarding."
`list_tags`	"What labels exist under `team-`?"
`graph_neighbors`	"What links to this ADR?"
`graph_subtree`	"Show the page tree under this root."
`graph_referenced_by`	"Who references this design?"
`graph_find_path`	"How is this page connected to that ticket?"
`work.*` (write)	"Add a comment to CMP-559." (gated by `READ_ONLY=false` + PAT)

Write tools follow a read → preview → commit discipline: the agent reads first, captures the current version, previews with dry_run=true, then commits with dry_run=false + expected_version=…. Concurrent edits to the same page are rejected — your change cannot stomp a teammate's.

Your agent can lean on Lantern's bundled skills (lantern-search, lantern-context-pack, lantern-explore-graph, lantern-write-back) for tool-routing guidance — see the repo's .claude/skills/.