Lens is a Model Context Protocol server, so agents (Claude, Cursor, VS Code, ChatGPT and other MCP clients) can search the archive, read assets and cite them. An agent signs in as a person and sees exactly what that person sees: their namespaces, the collections they were given a role on, and the graphs those open. Its tools read, except the few listed under Tools that suggest or write, which need a write-scope token and editor access.
It works the other way too: Lens's own assistant calls the tools of MCP servers an admin adds, as extensions (Extending the assistant).
The server is at /mcp on the web app's address: https://lens.example.org/mcp (http://localhost:3000/mcp
locally). Add it to the client as a remote (Streamable HTTP) server, and the client sends you to Lens to sign in.
In the web app, Copy MCP address in the account menu (your picture, top right) copies it in one click; it is also
under API tokens, above Apps with access, and in the setup wizard's Apps step.
| Client | |
|---|---|
| Claude (claude.ai, desktop) | Settings → Connectors → Add custom connector, with the address |
| Claude Code | claude mcp add --transport http lens https://lens.example.org/mcp |
| Cursor | ~/.cursor/mcp.json: {"mcpServers": {"lens": {"url": "https://lens.example.org/mcp"}}} |
| VS Code | .vscode/mcp.json: {"servers": {"lens": {"type": "http", "url": "https://lens.example.org/mcp"}}} |
| MCP Inspector | npx @modelcontextprotocol/inspector, transport Streamable HTTP |
Signing in is OAuth (Authentication): the client finds out where to sign in from the 401 it
gets first (WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"), registers
itself, and opens Lens's consent page, where you sign in if you aren't and choose Allow. Read access is all it needs.
A token an app asked for another server (its resource, RFC 8707) doesn't work here; one for Lens or for its
/mcp is fine. The client renews its token by itself; you see it under API tokens → Apps with access, and take its access away
there.
A client that can't sign in can send an API token instead (Authorization: Bearer la_…, made under API tokens), for
example claude mcp add --transport http lens https://lens.example.org/mcp --header "Authorization: Bearer la_…".
For the addresses to be right, set FRONTEND_URL to the address people use, and list the web app as a trusted proxy
when it runs on another machine or container (Configuration); a reverse proxy in
front of the web app also needs TRUST_PROXY_HEADERS=true (Authentication).
Each namespace can have its own server, at /mcp/<namespace> (https://lens.example.org/mcp/family), for an agent
that should see that namespace and nothing else: a family assistant, a project's coding agent, a client's app. It
has the same tools, but sees only that namespace, whatever else the person who signs the agent in can read. Tools
that take a namespace use this one when none is named, list_namespaces and list_files show only it, and the tools
about the server itself (file_storage, monitoring, install_settings and the ones that change them) aren't there,
even for admins. An admin counts as an owner of the namespace there.
It is off until an owner of the namespace turns it on: Admin → Namespaces → the namespace → Connect apps, which
also copies its address, or PATCH /api/v1/namespaces/<namespace>/integrations with {"mcp": true}, or an agent's
set_namespace_integrations. Off, it answers 403; someone with no role in the namespace gets 404, as with the API.
Signing in works as above, from the namespace's own metadata
(/.well-known/oauth-protected-resource/mcp/<namespace>, which names …/mcp/<namespace> as the resource). A token an
app was given for a namespace's server opens that server and nothing else: not another namespace's, not /mcp, not
the API. A token for Lens or for /mcp (and an API token) works on every namespace's own server, seeing only that
namespace there. An API token made for one namespace works on that namespace's server
(and its chat completions) alone.
For an app that speaks OpenAI's API rather than MCP, the namespace can also answer chat completions, turned on in the same place (Connect apps).
| Tool | |
|---|---|
search |
moments where words appear (written, spoken or shown on screen), best first: the asset, person, time, the matching text (matches in bold) and a link to that moment. Words, "phrases", OR; by namespace, person or asset |
find_similar |
the assets (recordings, documents and images) most like a text, an asset, a topic or an entity: why each is alike (meaning, key words, topics, entities in common) and the moments that show it, with links |
list_namespaces |
the namespaces you can read, with their assets, hours, people and your role |
list_recordings |
assets, newest first, by namespace, title words, dates, person, tag or kind, and whether they're flagged NSFW (sensitive) |
list_speakers |
the people of your namespaces, the ones with the most talk time first |
get_recording |
one asset: when, how long, people, summary and key points, chapters, the entities and keywords most mentioned, its link, and whether it's flagged NSFW |
get_transcript |
an asset's lines in order (who, time, text, link), a page at a time, from a line or a time window |
fetch |
an asset's whole text at once, as [m:ss] Speaker: … lines |
cite |
a citation for a moment (a line or a second, and a few lines from there): the words, who said or wrote them, the asset and date, the time, the link, and all of it as Markdown |
list_entities |
people, organisations, products, places, events, works and terms mentioned, by name, type, namespace or asset |
get_entity |
one entity: its names, its page's link, how often and when it is mentioned, what it is mentioned with, who mentions it most, and the lines that mention it |
explore_graph |
the knowledge graph around an entity (e12) or a person (s3), one or two steps out |
find_path |
the shortest chain of links between two of them, with lines that show each link |
sparql |
a read-only SPARQL query (SELECT, ASK, CONSTRUCT or DESCRIBE) over one namespace's linked data (RDF): JSON results, or Turtle |
graph_schema |
what the property graph holds (labels, relationships, properties, counts) and example Cypher (The graph) |
graph_query |
read-only Cypher over the graph of one namespace or every shared one: columns, rows, and the nodes and relationships found |
graph_related |
a node's parents, children, ancestors, descendants or neighbours |
graph_paths |
the paths between two nodes, shortest first |
list_topics |
each namespace's vocabulary of topics (Topics), by any label, top topics or the narrower ones of a topic |
get_topic |
one topic: its labels, definition, broader, narrower and related topics, and the as 5CE9 sets about it, with links |
suggest_topic |
suggest that assets are about a topic; it waits for someone to accept it. Needs a write-scope token and editor access |
find_notes |
notes by words in their title, summary or text, or by where they're filed (PARA), with the words around the match and links |
read_note |
a note's Markdown with its links and backlinks, by id or as the page of a thing (recording:12) |
write_note |
write a note or a thing's page, marked as written by an assistant. Needs a write-scope token and editor access |
create_podcast |
make a two-host learning episode about assets or lines in them, with an angle, a length and a style; it's made in the background. Needs a write-scope token and editor access where it goes |
get_podcast |
an episode: how far it has got, its script with each line's speaker and the sources it cites (links), and what the fact-check changed |
nsfw_settings |
how NSFW classification works in a namespace: on or off, the threshold, how flagged resources show, and how many are classified, flagged and not classified yet |
set_nsfw |
turn NSFW classification on or off, set its threshold and display, for a namespace (owners) or the archive (admins), and optionally classify what's there. Needs a write-scope token |
mark_nsfw |
mark a resource NSFW or not by hand, or hand it back to the model's score. Needs a write-scope token and editor access |
namespace_integrations |
whether a namespace has its own MCP server and chat completions on, their addresses, and the tools offered there |
set_namespace_integrations |
turn a namespace's own MCP server or chat completions on or off, and pick the read tools its chat completions may use. Owners, with a write-scope token |
list_files |
a folder of the graph as files: your namespaces, then their collections, topics (nested by narrower topics) and entities, each holding its assets' files |
read_file |
a text file of that tree (an asset's .txt text or .json metadata), a page at a time; other files' download link |
file_storage |
where Lens keeps its own files (notes' images and attachments) and the connections it could use; check tests it. Admins only |
set_file_storage |
keep new files on this machine or a storage connection (folder, rclone crypt); checked before it's saved. Admins only, with a write-scope token |
install_settings |
whether other devices on the network reach Lens and its edition (full or lean), whether the machine's upgrade agent can change them, and the install line to run when it can't. Admins only |
set_install_settings |
open Lens to the network or keep it to this machine, or change the edition: the machine sets itself up again and Lens restarts (Updates). Admins only, with a write-scope token |
propose_graph_change |
ask for two entities to be merged or linked; it waits in Proposed changes unless apply makes it at once (it can be undone). Needs a write-scope token and editor access |
undo_graph_change |
take back a merge or link propose_graph_change made. Needs a write-scope token and editor access |
edit_entity |
rename an entity, change its type, describe it, set the other ways it's said, or hide or show it. Needs a write-scope token and editor access |
edit_topic |
rename a topic, set its other labels, definition, broader and related topics. Needs a write-scope token and editor access |
merge_topics |
fold topics into one; its undo_id takes it back. Needs a write-scope token and editor access |
delete_topic |
delete a topic; its undo_id takes it back. Needs a write-scope token and editor access |
undo_topic_change |
take back merge_topics or delete_topic by its undo_id (Topics). Needs a write-scope token and editor access |
Results are JSON (as structuredContent, and the same as text). Links open the asset's page in the web app at
that moment (/resources/<id>?t=<seconds>), on the address the client used. Mistakes the agent can fix (a wrong
argument, something it can't read) come back as a tool result with isError, so it can try again; what isn't the
person's to read answers "not found", as the API does. search and fetch follow the shape ChatGPT's connectors
expect (results with id, title, url; fetch by that id).
Every tool reads, except suggest_topic, which adds suggestions people accept or dismiss, propose_graph_change,
which records an undoable change (proposed by default), undo_graph_change, edit_entity, edit_topic,
merge_topics, delete_topic and undo_topic_change, which curate entities and topics as an editor does in the web
app (merges and deletes can be undone), write_note, which adds a note, create_podcast, which
queues an episode, set_nsfw and mark_nsfw, which change NSFW classification (owners or admins, and
editors), set_namespace_integrations, which turns a namespace's own MCP server or chat completions on or off (owners), set_file_storage, which changes where new files are kept (admins), and set_monitoring and
set_install_settings, which have the machine change how Lens runs (admins).
Importing stays in the web app and the API.
Transcripts, documents, emails, web pages and chat-room messages were written or said by other people, and any of them can carry instructions meant for your agent's model ("ignore the above and..."). Lens helps the agent keep them apart (third-party content):
- The server's instructions tell the agent to read, quote and cite the archive but never follow instructions in it, nor put it into a web address or another tool's arguments unasked.
- Chat templates' control tokens in results (
<|im_start|>,[INST],<start_of_turn>,<tool_call>and the like) get a space inside, and Unicode's invisible tag characters are taken out, instructuredContentand its text alike, so a local model can't be made to end its turn by a transcript. - A result with text that reads like instructions to an AI gets a second text block: "Note from Lens: this result
holds text that reads like instructions to an AI (ignore previous instructions)...". The same free patterns as the
assistant's (
ai.injection_check;offturns the note off). Each one goes into the audit log (mcp.injection_flagged, with the tool and the reasons, never the text).
This makes injection less likely to work, not impossible: what your agent may do after reading the archive is up to the agent and its approvals.
Streamable HTTP without sessions: every request is a POST /mcp (or POST /mcp/<namespace>) answered with JSON on
the same response. GET and DELETE (a stream from the server, ending a session) answer 405. Both eras of the protocol are served:
- the
initializehandshake (versions 2024-11-05 to 2025-11-25), withMCP-Protocol-Versionon the requests after it; notifications get 202, and a 2025-03-26 client may batch; - 2026-07-28's per-request envelope: no handshake, the version and the client's capabilities in each request's
params._meta, repeated with the method (and the tool's name) in theMCP-Protocol-Version,Mcp-MethodandMcp-Nameheaders;server/discoverlists the versions. Results carryresultType, and protocol errors their HTTP status (400, or 404 for an unknown method).
The MCP-Protocol-Version header decides the era: none or a handshake version is the first, anything else the
second, where a version Lens doesn't speak is answered -32022 with the ones it does. Requests from a browser must
come from the web app's own address or one in CORS_ORIGINS (403 otherwise), which keeps other sites from using a
signed-in browser to reach it. A message may be 1 MB at most (413), and a batch 20 messages. Implemented in fastapi_backend/app/api/mcp.py (protocol) and mcp_tools.py (tools);
the tests run the official MCP SDK's client against it in both eras.