@latten/installer

The Latten Installer is the deterministic senses a coding agent uses to see where a TypeScript app reaches into LLMs, data, and other services, wire those crossings into Latten, and read back what it found — read-only, with every change landing as a reviewable PR a human approves. Shipped as an MCP server (latten-mcp) and a companion skill (latten-instrument). The agent supplies the judgment, the diff, and the PR; this package supplies the tools it calls.

If you only downloaded the package, nothing has reached Latten yet. The valuable step is connecting it as an MCP server and letting your agent call provision, guide, scan, verify, and receipt. Provisioning connects to your Latten account — your agent hands you one link, you sign in (or create a free account) and click Approve, and everything it observes lands on your console from the first crossing; the first receipt is free. A trial or paid plan adds history, recommendations, agent-applied fix PRs, verification, and team context.

Setup in your agent

The server speaks stdio MCP; every client below gets the same experience — connect, call provision if no token exists, call guide, follow it. LATTEN_URL points at the Console. LATTEN_TOKEN is optional up front: if you omit it, the agent calls provision, shows you a connect link to approve (your one step), and collects a token already attached to your account.

Codex (CLI and desktop) — ~/.codex/config.toml:

[mcp_servers.latten]
command = "npx"
args = ["-y", "@latten/installer"]
env = { LATTEN_URL = "https://latten.io" }

Then ask Codex:

Use the Latten MCP. If there is no LATTEN_TOKEN, call provision once — it returns a connect link; show it to me, I approve in the browser, then poll provision with the device_code for the token. Then read guide, scan this repo, instrument high-confidence TypeScript crossings with @latten/sdk, open a reviewable PR, verify real crossings, and return the receipt.

Claude Code

claude mcp add latten \
  -e LATTEN_URL=https://latten.io \
  -- npx -y @latten/installer

(Claude Code users also get the latten-instrument skill; other clients get the identical choreography from the guide tool.)

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "latten": {
      "command": "npx",
      "args": ["-y", "@latten/installer"],
      "env": { "LATTEN_URL": "https://latten.io" }
    }
  }
}

Gemini CLI — ~/.gemini/settings.json:

{
  "mcpServers": {
    "latten": {
      "command": "npx",
      "args": ["-y", "@latten/installer"],
      "env": { "LATTEN_URL": "https://latten.io" }
    }
  }
}

If you already created a connection in Latten Console, include LATTEN_TOKEN=ltnpx_... and provision is skipped. Otherwise the agent hands you the connect link, collects the account-bound token after your approval, and returns the value path and receipt after verification.

Then ask your agent: "instrument this app with Latten" — it provisions if needed, reads guide, scans, places the SDK calls, opens the PR, verifies real crossings, and returns the receipt.

The seven tools

The MCP server (buildServer(), exposed by the latten-mcp bin over stdio) registers:

• guide({}) — the placement playbook, served by the server itself so every MCP client (Gemini, Claude Desktop, Codex, Claude Code) follows the same contract: where SDK calls go (every LLM call, data touch, external API, agent handoff, plus the actor seed), naming, the reviewable-PR rule, and the verify/fix loop. The server's MCP instructions tell agents to read it first.
• provision({ name?, endpoint?, device_code? }) — the bootstrap, account-connected. Call when there is no LATTEN_TOKEN: the first call returns a connect_url + short code the agent shows its human (sign in or free account, one Approve click); calling again with the returned device_code collects the proxy token, born already attached to that account, plus console_url and a short value path the agent can repeat in its handoff.
• scan({ repoPath }) — static analysis only. scanRepo(repoPath) walks a repo's .ts source with ts-morph and returns candidate crossings — DB queries, fetch/HTTP calls, and LLM-SDK calls — each with a kind, a suggestedTarget, a suggestedAction, and a confidence. Detection is library-signature based (it matches imported modules against a catalog, then call patterns), so it needs only source — no node_modules. Candidates are proposals; the skill judges which to instrument and refines targets. scan never implies coverage beyond its catalog.
• verify({ since? }) — the reveal. Asks the console which crossings have actually arrived for this app since a timestamp, returning a digest (count, sources, targets, findings, firstSeenAt) that drives the "waiting… ✓ received" moment and the first shocking finding.
• receipt({ since? }) — the trust artifact. Pulls the human-facing receipt after crossings arrive: reached data domains and models, attribution quality, cost, fixes available, the trial state, the zero-PII-values attestation, and the calm account path for keeping history, recommendations, fix PRs, and verification.
• recommendations({}) — the fix list. Pulls the console's recommended boundary per open exposure for this app. Returns 402 if the app isn't on a trial/paid plan.
• fix({ findingId }) — one recommendation by id, so the agent can propose the diff, let the human review, and land it. Latten only serves the recommendation; the agent does the edit and the human approves — the console never executes.

verify, recommendations, and fix reach the console at LATTEN_URL and authenticate with the app's proxy token (LATTEN_TOKEN) — the token is the app's identity. Both are overridable per-call. Wire fields stay snake_case to match the engine and every other Latten client.

Where the token may be sent

The proxy token is a bearer credential, so the endpoint is locked down. The token is only sent over https (an http endpoint is allowed only for localhost during development), and only to an allowlisted host:

• the host of LATTEN_URL (your configured console), plus
• any hosts in LATTEN_ALLOWED_HOSTS (comma-separated) — set this to authorize a self-hosted console when you pass the endpoint as a literal argument with no LATTEN_URL in the env;
• if neither is set, the default Latten SaaS host (latten.io).

Because the MCP tools accept endpoint as a per-call argument, this pin is what stops a prompt-injected agent from redirecting your app token to an unrecognized host: a mismatched endpoint is refused, not sent.

The skill

skill/SKILL.md (latten-instrument) is the choreographer: discover → scan → judge & instrument → prove (typecheck/build) → PR → reveal. scan and verify/recommendations/fix are its deterministic senses; everything else — judgment, the diff, the reviewable PR, the reveal — is the agent. The output is always a reviewable PR: for a security buyer, a reviewable diff is the precondition for trust.

scan limitations (by design — it is a candidate-proposer, not the final word)

• Over-proposes on shared method names. Rules fire on any .query/.execute/.create call in a file that imports the relevant library — there is no dataflow check that the call is on that client. An unrelated .execute() in a DB-importing file is flagged. The skill refines.
• Raw-SQL targets only. Target/action are derived from a string-literal first argument (from/into/update <table>, leading SQL verb). Query-builder ORMs (knex, drizzle, typeorm, prisma) that build SQL via chained calls degrade to a generic data_domain:db / read — still flagged as a crossing, just with a target the skill must refine.
• TypeScript only — the language frontier expands as each SDK language ships.