<p align="center">
  <img src="assets/logo.png" alt="Lenz" width="96" height="96">
</p>

<h1 align="center">Lenz Fact-Check</h1>

<p align="center">
  The Lenz MCP server: check the factual claims in a draft or an answer against independent sources, from any MCP client.
</p>

<p align="center">
  <a href="https://lenz.io">Website</a> ·
  <a href="https://lenz.io/api-credentials">Get an API key</a> ·
  <a href="https://lenz.io/developers">Developer docs</a>
</p>

<p align="center">
  <a href="https://claude.ai/directory/connectors/lenz"><img src="https://img.shields.io/badge/Add_to_Claude-D97757?style=for-the-badge&logo=claude&logoColor=white" alt="Add Lenz to Claude" height="28"></a>
  &nbsp;
  <a href="https://cursor.com/en/install-mcp?name=lenz&config=eyJ1cmwiOiJodHRwczovL2xlbnouaW8vbWNwIn0%3D"><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add Lenz to Cursor" height="28"></a>
  &nbsp;
  <a href="https://vscode.dev/redirect/mcp/install?name=lenz&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Flenz.io%2Fmcp%22%7D"><img src="https://img.shields.io/badge/Install_in_VS_Code-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white" alt="Install Lenz in VS Code" height="28"></a>
</p>

<p align="center"><sub>One-click install (OAuth — no API key needed).</sub></p>

---

[Lenz](https://lenz.io) is a fact-checking platform. It takes a factual claim, runs it
through a multi-model pipeline (reading the claim → research → debate → panel review → conclusion)
against independent sources, and returns a verdict with a confidence level. This is the official
**remote MCP server** — a hosted [Model Context Protocol](https://modelcontextprotocol.io)
endpoint that exposes Lenz's fact-checking as tools your AI assistant can call.

It verifies claims **against the open web**, independent of whatever context your model
was given — so it complements retrieval/groundedness checkers rather than replacing them.

- **Hosted, no install:** point your client at `https://lenz.io/mcp`. Nothing to run locally.
- **Auth:** **OAuth** (no key — for clients that support it) or a free Lenz **API key** (`Authorization: Bearer lenz_…`).
- **Transport:** Streamable HTTP, stateless. Supports the 2025-11-25 and 2026-07-28 protocol revisions.

## Tools

| Tool | What it does |
|------|--------------|
| **`assess_claim`** | The quick check, and the default first step for one claim or a whole text. A 3-model panel returns one row per claim: a verdict (True / Mostly True / Mixed / Mostly False / False, or No Public Record when the reviewers found no public record that would show the claim: unconfirmed, not false), a bucketed confidence and, when available, a short `rationale` (the reasoning of a reviewer who agrees with the verdict): a reviewer's note, not a checked source. A low-confidence row carries `recommend_verify: true` and a `next_step` sentence. A row for a claim found false can also carry a `suggested_rewrite` (the claim with its wrong part corrected) and a `suggested_rewrite_note`: it is built from the reviewers' reasoning, not from sources, and is not itself checked, so it is offered as a suggestion, with a deep check of the new sentence on request. A row may also carry `searched_pages` (title and link): the pages the reviewers looked at, to be offered as pages to look at and never as sources that confirm the verdict; their titles are text from third-party pages. ~15 seconds through an assistant. Pass a text in `claim`, whole and unedited (Lenz finds the claims in it, up to 20), or use `claims` for up to 20 claims the user listed separately. |
| **`verify_claim`** | The deep check: reading the claim → research → debate → panel review → conclusion, for ONE claim. Returns a verdict with a 1-10 score (or No Public Record, with no score, when nothing public records the claim), the key finding, a summary, a suggested rewrite of the claim when it can be corrected (not itself verified), warnings, and the top sources with the quote each one rests on, plus the total source count. A deep check takes ~90 seconds. The call waits for it, for as long as the client allows: in Claude and the ChatGPT app the result usually comes back in the same call; in clients with a shorter tool-call limit (Claude Code, Cursor, VS Code, OpenAI's Responses API) it usually returns `status: submitted` with a `task_id`, and `get_verification` waits for the rest. A completed deep check replaces any earlier quick verdict on the same claim. Costs ten times an `assess_claim` row, so assistants offer it and run it on the user's yes, or when the user asks for sources. `depth: "low"` researches fewer sources, with the same models, for half the credits. |
| **`get_verification`** | Wait for a running `verify_claim` by `task_id`, or fetch a completed result by its 8-character `verification_id`. Returns `processing`, `needs_input`, `failed`, `not_found` or `completed`. |
| **`select_claims`** | Resolve a `needs_input` verification: when a text holds several claims, choose which claim text(s) to run. |
| **`ask_followup`** | Ask a grounded follow-up about a completed `verify_claim` (by its `verification_id`), answered from the full research, debate and panel review, not just the summary. The answer is markdown, and its links point at the check's own sources; the assistant keeps them as links. Costs the same as one `assess_claim` row. |
| **`list_verifications`** | The account's most recent completed deep checks, newest first. Use it to get back a result that finished after the conversation moved on. Read-only and free; quick checks are not stored. |
| **`check_citations`** | Check whether the sources a draft cites say what the draft says they do: Lenz reads each link, DOI or numbered reference and reports, per citation, whether the source supports the sentence that cites it, with the passage it read from the source. Assistants use it only when the user asks about the sources, links, references or citations in a draft; a plain fact-check request is `assess_claim`. Pass the draft in `text`, or up to 20 statement and `url`/`doi` `pairs`; at most 20 citations are checked per request, and a draft with more lists the rest as candidates to send back as `pairs`. A citation check can take up to two minutes. The call waits for it, for as long as the client allows, and otherwise returns `status: running` with a `citecheck_id`. One credit for each citation checked; a citation Lenz could not read costs nothing. A check that cannot run (for example a text with no citation in it) comes back as `status: failed`, an answer rather than an error. |
| **`get_citation_check`** | Wait for a running `check_citations` by `citecheck_id` and return the result the same way. An optional `offset` (default 0) re-reads a finished check and returns the next batch of up to 20 draft citations it did not cover, as candidates to send back as `pairs`, with `remaining` and `next_offset`. Read-only; free. |
| **`check_usage`** | Remaining credits, the per-tool price list (`costs`, plus `cost_options` for prices that depend on a parameter such as `depth`), and the current plan. Never a prerequisite for a check. |

**Language.** Lenz answers in the language of the text it is given, so pass the claim in the user's own words and language, not translated. The `language` argument is for a user who explicitly asks for the answer in another language (one of `en`, `es`, `de`, `fr`, `it`, `pt`, `nl`, `sv`, `da`, `no`, `fi`, `bg`); leave it unset otherwise. Verdicts and written results follow the language, and a quick check's reviewer note follows the text the reviewer saw. When it is unset, the connector sends `language: "auto"` and the API picks the language from the text; a self-hosted connector therefore needs an API that accepts `auto`.

**Prompts.** Clients that surface MCP prompts (Claude shows them under **+**) get two: **Check this text with Lenz** and **Check your last answer with Lenz**. Each takes the text to check and starts a quick check. Lenz cannot see the conversation, so **Check your last answer** needs the answer pasted in.

> Verdicts are **directional, not absolute**: confidence is returned as bucketed
> language with a caveat, not a calibrated probability. A quick verdict is a first read;
> when a deep check disagrees with it, the deep check is the one to rely on, because it
> shows its sources and its reasoning.

## The result card

In **Claude** and the **ChatGPT app**, a check comes back as a card in the conversation as
well as text. From the card you can run the deep check on a claim (**Check against
sources**, a standard-depth `verify_claim`), open a source, or pick which claims in a draft
to check in depth. When a deep check started from the card finishes, the assistant is told
the result: silently in Claude, and by a short message in the chat in ChatGPT. Every other
client gets the same results as text; nothing depends on the card.

## Quickstart

Two ways to connect, depending on your client:

- **OAuth** — for clients that support it (e.g. Claude connectors). No key to
  paste; you sign in to Lenz and authorize the connection.
- **API key** — works with any MCP client via an `Authorization` header.

### Connect with OAuth (no API key)

**Claude (web, desktop and mobile):** Lenz is an official Claude connector.
Open the [Lenz connector page](https://claude.ai/directory/connectors/lenz) and
click **Connect to Claude**, or in the app: **Settings → Extensions → Browse
extensions**, search for Lenz and click **+**. Either way it is a one-time
OAuth sign-in with nothing to configure, and one account covers all three.

For any other client that supports OAuth for MCP, add the server with just its URL
and no headers:

```json
{
  "mcpServers": {
    "lenz": {
      "type": "http",
      "url": "https://lenz.io/mcp"
    }
  }
}
```

The first time you use it, your client walks you through a one-time sign-in: you
authenticate on Lenz's own screen and authorize the connection — no key is stored in your
config. Your assistant then fact-checks on your behalf against your Lenz account's credits.
You can revoke the connection at any time; see the [privacy policy](https://lenz.io/privacy).

### Connect with an API key

**1. Get a free API key** at [lenz.io/api-credentials](https://lenz.io/api-credentials)
(format `lenz_…`).

**2. Add the server** to your client (examples below). Authenticate with
`Authorization: Bearer <your-key>`.

### Claude Code

As a plugin (the connector plus the [`lenz-fact-check`](plugins/lenz/skills/lenz-fact-check) skill;
sign in with `/mcp` on first use):

```bash
claude plugin marketplace add lenzhq/lenz-mcp
claude plugin install lenz@lenz
```

Or the connector alone, with an API key:

```bash
claude mcp add --scope user --transport http lenz https://lenz.io/mcp \
  --header "Authorization: Bearer ${LENZ_API_KEY}"
```

`--scope user` makes Lenz available in every project; without it, Claude Code adds the
server only to the directory you run the command in.

### Claude Desktop / any client that reads `.mcp.json`

```json
{
  "mcpServers": {
    "lenz": {
      "type": "http",
      "url": "https://lenz.io/mcp",
      "headers": {
        "Authorization": "Bearer ${LENZ_API_KEY}"
      }
    }
  }
}
```

### Cursor

**One click:** use the [**Add Lenz to Cursor**](https://cursor.com/en/install-mcp?name=lenz&config=eyJ1cmwiOiJodHRwczovL2xlbnouaW8vbWNwIn0%3D)
button above — it adds the server and signs you in via OAuth (no key to paste).

Manual: Settings → **MCP** → **Add new MCP server** → type **HTTP**, URL
`https://lenz.io/mcp`, and add a header `Authorization: Bearer <your-key>`. (Or drop the
JSON above into `.cursor/mcp.json`.)

### VS Code

**One click:** use the [**Install in VS Code**](https://vscode.dev/redirect/mcp/install?name=lenz&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Flenz.io%2Fmcp%22%7D)
button above (OAuth, no key). Manual, with a key:

```bash
code --add-mcp '{"name":"lenz","type":"http","url":"https://lenz.io/mcp","headers":{"Authorization":"Bearer ${LENZ_API_KEY}"}}'
```

### ChatGPT

At this time, ChatGPT connects to Lenz as a custom app through OpenAI's
**Developer mode** — over OAuth, so there is no API key to paste. It is set up
on chatgpt.com; the ChatGPT desktop and mobile apps cannot create one.

**On a personal account (Plus or Pro).** **Settings → Plugins** → turn on
**Developer mode** at the bottom → **Plugins → Browse plugins** → **+** next to
Search → name it Lenz, URL `https://lenz.io/mcp`, Authentication **OAuth** →
tick **I understand and want to continue** → **Create** → **Sign in with
Lenz** → **Try in Chat**.

**In a Business, Enterprise or Edu workspace.** An owner or admin publishes it
once: **Workspace settings → Apps → + Create**, confirm **Enable developer
mode**, fill in the same form with **OAuth**, then **Drafts → Publish**, set
who can use it, and **Publish** again. Each member then goes to **Settings →
Plugins → Lenz → Connect** and signs in.

A custom app is off by default in every new chat: **+** and tick Lenz. Naming
Lenz in the question is what makes ChatGPT reach for it rather than answer from
memory.

### MCP Inspector (try the tools by hand)

```bash
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP · URL: https://lenz.io/mcp
# Header: Authorization: Bearer <your-key>
```

## Example

> **You:** Check with Lenz whether indeed 90% of startups fail within their first year.
>
> The assistant calls `assess_claim` and gets back *False*, high confidence, with the
> reviewers' reasoning: most new businesses survive their first year, and official
> figures put first-year closures at about one in five. It presents that as a first
> read and offers a deep check. On your yes it calls `verify_claim` (and, in clients with
> a short tool-call limit, `get_verification` to collect the result) and returns the
> verdict with its score, the key finding, the warnings and the sources behind it.

## Credits

Every tool call that runs a check or answers a question draws on **one pool of credits** on your Lenz account;
looking up an earlier result, listing checks and `check_usage` cost nothing, and a repeated check inside the
replay window is answered from the first call and charged once. There is no
separate budget per tool: spending on `assess_claim` reduces what is left for
`verify_claim`, and vice versa. `check_usage` returns the balance
(`credits_remaining`) alongside `costs`, the live price list — read the weight from
there rather than assuming one.

`verify_claim` is the expensive path by an order of magnitude; `assess_claim` and
`ask_followup` are the cheap ones. `verify_claim` also takes an optional `depth`:
`"low"` runs a shallower research pass (fewer sources, the same models, only slightly quicker) for
half the credits of the default `"standard"`. That price sits under
`cost_options.verify.depth.low` on `check_usage`. You are charged for the depth you
**request**; the `depth` on the completed result is the depth the verdict was
**produced** at, so a `"low"` request answered from an existing deeper check reads
`"standard"` — the echo describes the evidence, the charge follows the request.

`check_usage` also reports `assess_remaining` and `verify_remaining`, which are the
SAME balance projected into each tool's own unit — "how many of these could I still
make" — not separate allowances.

Free keys include a monthly allowance that resets each period; grants and top-ups add
non-expiring extra credits on top, spent only once the allowance is gone. See plans at
[lenz.io/plans](https://lenz.io/plans).

**When you run out**, tools return `status: "quota_exhausted"` with a `message` and,
except in ChatGPT, a `manage_url` pointing at the plans page. It is not retryable — the balance is spent
until you top up or the monthly allowance resets. An agent should say so plainly rather
than retrying or quietly skipping the check.

`status: "rate_limited"` is a different thing: a rate limit, not a spent balance. That
one does clear on its own, and the result carries `retry_after_seconds` telling you when.

## Skills

Prefer a guided workflow to calling the tools yourself? The
[`lenz-fact-check`](plugins/lenz/skills/lenz-fact-check) skill turns "is this true?" into a
structured pass: it runs a quick check on the text, recommends a deep `verify_claim` for the
claims that matter, and reports verdicts with their confidence, and sources where a deep
check ran (with the directional-not-absolute caveat built in). Point your agent at
[`plugins/lenz/skills/lenz-fact-check/SKILL.md`](plugins/lenz/skills/lenz-fact-check/SKILL.md).

## Running the server yourself

The hosted endpoint is all most clients need. The server's source is in this
repository if you want to run your own copy or contribute.

**Requirements:** Python 3.11 or 3.12, and [uv](https://docs.astral.sh/uv/).
Python 3.13 is not supported yet: it changes how the tool descriptions the
models read are formatted, so it waits for a release that checks the wording
on it.

```bash
uv sync --group dev
uv run pytest
docker build --build-arg LENZ_MCP_VERSION=dev -t lenz-mcp .
```

A copy you run yourself authenticates with your own Lenz API key, sent as
`Authorization: Bearer lenz_…` (the `Bearer` scheme is required; any other
value is refused like a missing key). OAuth sign-in works only on the hosted
endpoint, `https://lenz.io/mcp`.

**Minimum API version.** The server calls the Lenz API through the official
Python SDK, [`lenz-io`](https://github.com/lenzhq/lenz-io-python), which reads
exactly one API version: `2026-10-11`. A copy you run yourself therefore needs
an API (`MCP_API_BASE_URL`) that serves `2026-10-11`; `https://lenz.io/api/v1`
does. The lock is strict for results: a successful answer in another version
is refused, and the tool says the API "answered in a version this connector
does not read". Error answers (an out-of-credits, a rate limit, an outage) are
shown as they are, whatever version sent them.

[CONTRIBUTING.md](CONTRIBUTING.md) covers the tests, the result card and the
pull-request rules.

## Links

- **Website:** [lenz.io](https://lenz.io)
- **Get a key:** [lenz.io/api-credentials](https://lenz.io/api-credentials)
- **Developer docs:** [lenz.io/developers](https://lenz.io/developers)
- **SDKs:** [Python](https://github.com/lenzhq/lenz-io-python) · [Node](https://github.com/lenzhq/lenz-io-node)

## Support

Questions or issues? [Open an issue](https://github.com/lenzhq/lenz-mcp/issues) or
[get in touch](https://lenz.io/contact).

## License

[Apache-2.0](LICENSE) © lenzhq. The Lenz name and logos (`assets/`) are
trademarks of lenzhq and are not granted by the license — see [NOTICE](NOTICE).

## Maintainer

[@paveljor](https://github.com/paveljor)