Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
time and a link, as Markdown), `list_entities`, `get_entity`, `explore_graph` and `find_path`. Links open the
recording at that moment in the web app. Streamable HTTP without sessions, in both protocol eras (the 2025
`initialize` handshake and 2026-07-28's per-request envelope); an API token works for clients that can't sign in
(docs/mcp.md).
(docs/mcp.md). An app's token keeps the server it was asked for (`resource`, RFC 8707), and the MCP server refuses
one asked for another.
- **Opt-in telemetry.** Lens can send OpenTelemetry traces and metrics about its own work to a collector you choose:
API requests by route, jobs and each step, routines, workflow runs, and model calls with their tokens and an
estimated cost (from per-model prices you set). It is off by default and never on unless you turn it on, in
Expand Down
5 changes: 3 additions & 2 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ locally). Add it to the client as a remote (Streamable HTTP) server, and the cli
Signing in is OAuth ([Authentication](authentication.md#oauth)): 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.
The client renews its token by itself; you see it under API tokens → Apps with access, and take its access away
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
Expand Down Expand Up @@ -71,5 +72,5 @@ Streamable HTTP without sessions: every request is a `POST /mcp` answered with J
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. Implemented in `fastapi_backend/app/api/mcp.py` (protocol) and `mcp_tools.py` (tools);
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.
3 changes: 2 additions & 1 deletion fastapi_backend/app/api/deps.py
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ class Principal:
sid: str | None = None
roles: dict[int, str] = field(default_factory=dict)
collections: dict[int, dict[int, str]] = field(default_factory=dict) # roles on collections: {space: {collection: role}}
resource: str | None = None # an app's token: the server it was given for (RFC 8707), when the app named one

@property
def can_write(self) -> bool:
Expand All @@ -76,7 +77,7 @@ def _principal(request: Request, db: DB) -> Principal | None:
elif raw.startswith("lo_"):
u = oauth.token_account(db, raw)
if u:
p = Principal(u["id"], u["email"], u.get("name"), bool(u.get("admin")), "oauth", u["scope"])
p = Principal(u["id"], u["email"], u.get("name"), bool(u.get("admin")), "oauth", u["scope"], resource=u.get("resource"))
elif raw:
claims = security.decode_access_token(raw)
u = auth.active_account(db, claims.account) if claims and auth.session_active(db, claims.sid) else None
Expand Down
35 changes: 33 additions & 2 deletions fastapi_backend/app/api/mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@
HANDSHAKE = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
PER_REQUEST = ("2026-07-28",)
MAX_BODY = 1_000_000
MAX_BATCH = 20 # messages in one batch (2025-03-26), each of which may search
SERVER_INFO = {"name": "lens", "title": settings.PROJECT_NAME, "version": __version__}
CAPABILITIES = {"tools": {"listChanged": False}}
INSTRUCTIONS = (
Expand Down Expand Up @@ -222,6 +223,31 @@ def handle_per_request(message: Any, request: Request, ctx: mcp_tools.Context) -
return {"jsonrpc": "2.0", "id": mid, "result": result}, 200


def _audience_ok(request: Request, resource: str | None) -> bool:
"""An app's token that names the server it is for (RFC 8707) must name this one: Lens, or its MCP server, on any
address Lens is reached at. Tokens that name none (API tokens, apps that didn't say) are Lens's."""
if resource is None:
return True
bases = {public_base(request), web_app_base(request), settings.FRONTEND_URL}
return resource.rstrip("/") in {b.rstrip("/") + end for b in bases for end in ("", PATH)}


async def _read(request: Request) -> bytes | None:
"""The body, or None when it's more than MAX_BODY: told by Content-Length, or found while reading, so a large one
is never held whole."""
try:
if int(request.headers.get("content-length") or 0) > MAX_BODY:
return None
except ValueError:
pass # a malformed length: reading tells
body = bytearray()
async for chunk in request.stream():
body += chunk
if len(body) > MAX_BODY:
return None
return bytes(body)


@router.post(PATH)
async def post(request: Request, db: Db) -> Response:
if not _origin_ok(request):
Expand All @@ -232,8 +258,11 @@ async def post(request: Request, db: Db) -> Response:
user = await run_in_threadpool(optional_user, request, db) # the database blocks
if not user:
raise HTTPException(401, "sign in first", headers={"WWW-Authenticate": "Bearer"})
body = await request.body()
if len(body) > MAX_BODY:
if not _audience_ok(request, user.resource):
# a token an app was given for another server (RFC 8707) isn't one to use here; the app asks again for this one
raise HTTPException(401, "this token was given for another server", headers={"WWW-Authenticate": "Bearer"})
body = await _read(request)
if body is None:
return JSONResponse(Fault(INVALID_REQUEST, "the message is too large").error(None), status_code=413)
try:
message = json.loads(body)
Expand All @@ -247,6 +276,8 @@ async def post(request: Request, db: Db) -> Response:
if isinstance(message, list):
if not message:
return JSONResponse(Fault(INVALID_REQUEST, "an empty batch").error(None), status_code=400)
if len(message) > MAX_BATCH:
return JSONResponse(Fault(INVALID_REQUEST, f"a batch may hold {MAX_BATCH} messages at most").error(None), status_code=400)
answers = [a for m in message if (a := await run_in_threadpool(handle, m, ctx)) is not None]
return JSONResponse(answers) if answers else Response(status_code=202)
answer = await run_in_threadpool(handle, message, ctx)
Expand Down
2 changes: 1 addition & 1 deletion fastapi_backend/app/api/mcp_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -748,7 +748,7 @@ def _entities(
"it most, and the lines that mention it (newest first), each with a url to that moment.",
Arg("entity_id", "integer", "the entity (from list_entities, get_recording or the graph)", required=True),
Arg("mentions", "integer", "how many mentioning lines", default=10, minimum=0, maximum=100),
Arg("mentions_offset", "integer", "skip this many lines (for the next page)", default=0, minimum=0),
Arg("mentions_offset", "integer", "skip this many lines (for the next page)", default=0, minimum=0, maximum=10000),
Arg("sort", "string", "the lines' order", default="newest", enum=("newest", "oldest", "most")),
)
def get_entity(ctx: Context, entity_id: int, mentions: int, mentions_offset: int, sort: str) -> dict[str, Any]:
Expand Down
22 changes: 14 additions & 8 deletions fastapi_backend/app/domain/oauth.py
Original file line number Diff line number Diff line change
Expand Up @@ -233,12 +233,13 @@ def _verifier_ok(verifier, challenge):
return hmac.compare_digest(calc, challenge or "")


def _issue(db, cfg, grant, uid, scope):
def _issue(db, cfg, grant, uid, scope, resource=None):
life = lifetimes(cfg)
access, refresh = "lo_" + secrets.token_urlsafe(32), "lr_" + secrets.token_urlsafe(32)
ttl = life["access_minutes"] * 60
ends = _later(life["refresh_days"] * 86400)
base = {"gid": grant, "account": uid, "scope": scope, "created_at": store.now()}
# resource: the server the tokens are for (RFC 8707), when the app named one; that server checks it
base = store.clean({"gid": grant, "account": uid, "scope": scope, "resource": resource, "created_at": store.now()})
# a grant revoked while its app was renewing gets nothing: the tokens hang off the grant
if not db.rows("UPDATE $g SET expires_at = $ends RETURN id", g=R("oauth_grant", grant), ends=ends):
raise OAuthError("invalid_grant", "this access was revoked")
Expand Down Expand Up @@ -287,18 +288,22 @@ def exchange_code(db, cfg, client_id, client_secret, code, redirect_uri, verifie
"name": c["name"],
"uri": c.get("uri"),
"scope": row["scope"],
"resource": row.get("resource"),
"created_at": store.now(),
},
c=R("oauth_client", c["id"]),
)
return _issue(db, cfg, gid, row["account"], row["scope"]), {"id": gid, "account": row["account"], "client": c["id"], "name": c["name"]}
tokens = _issue(db, cfg, gid, row["account"], row["scope"], row.get("resource"))
return tokens, {"id": gid, "account": row["account"], "client": c["id"], "name": c["name"]}


def refresh(db, cfg, client_id, client_secret, raw):
"""A new pair for a refresh token, which then stops working. One that was swapped a while ago and comes back
ends the grant: it was probably copied."""
c = _client(db, client_id, client_secret, check_secret=True)
t = db.one("SELECT gid, account, kind, scope, expires_at, rotated, rotated_at FROM $r", r=R("oauth_token", auth.sha(raw or "")))
t = db.one(
"SELECT gid, account, kind, scope, resource, expires_at, rotated, rotated_at FROM $r", r=R("oauth_token", auth.sha(raw or ""))
)
g = db.one("SELECT client FROM $r", r=R("oauth_grant", t["gid"])) if t else None
if not t or not g or t["kind"] != "refresh" or g["client"] != c["id"] or t["expires_at"] < store.now():
raise OAuthError("invalid_grant", "the refresh token is wrong, was revoked or has expired")
Expand All @@ -318,22 +323,23 @@ def refresh(db, cfg, client_id, client_secret, raw):
now=now,
g=t["gid"],
)
return _issue(db, cfg, t["gid"], t["account"], t["scope"])
return _issue(db, cfg, t["gid"], t["account"], t["scope"], t.get("resource"))


def token_account(db, raw):
"""The account an access token acts as ({…account, scope}), or None. Refresh tokens don't open the API."""
"""The account an access token acts as ({…account, scope, grant, resource}), or None. Refresh tokens don't open
the API. resource is the server the token was given for, when the app named one."""
if not raw or not raw.startswith("lo_"):
return None
t = db.one("SELECT gid, account, kind, scope, expires_at FROM $r", r=R("oauth_token", auth.sha(raw)))
t = db.one("SELECT gid, account, kind, scope, resource, expires_at FROM $r", r=R("oauth_token", auth.sha(raw)))
if not t or t["kind"] != "access" or t["expires_at"] < store.now():
return None
u = auth.active_account(db, t["account"])
if not u:
return None
if not db.rows("UPDATE $r SET last_used_at = $n RETURN id", r=R("oauth_grant", t["gid"]), n=store.now()):
return None # its grant is gone
return {**u, "scope": "write" if can_write(t["scope"]) else "read", "grant": t["gid"]}
return {**u, "scope": "write" if can_write(t["scope"]) else "read", "grant": t["gid"], "resource": t.get("resource")}


# ---------- grants: the apps a person gave access to ----------
Expand Down
31 changes: 30 additions & 1 deletion fastapi_backend/tests/api/test_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
from fastapi.testclient import TestClient

from app.api import mcp, mcp_tools
from tests.api.test_oauth import _bearer, _grant
from tests.api.test_oauth import O, _bearer, _grant
from tests.helpers import login, make_user, seed

MODERN = "2026-07-28"
Expand Down Expand Up @@ -79,6 +79,26 @@ def test_clients_are_sent_to_sign_in(client, app, env):
assert client.post("/mcp", headers=env["h"], json={"jsonrpc": "2.0", "id": 1, "method": "ping"}).status_code == 401


def test_tokens_given_for_another_server(client, env):
# an app names the server it wants a token for (RFC 8707); one for Lens or its MCP server works here, on any
# address Lens is reached at, and keeps working when renewed
renew = lambda app, t: client.post( # noqa: E731
f"{O}/token", data={"grant_type": "refresh_token", "client_id": app["client_id"], "refresh_token": t["refresh_token"]}
)
for resource in ("http://127.0.0.1/mcp", "http://localhost:3000/mcp", "http://localhost:3000/", "http://127.0.0.1"):
app, t = _grant(client, env["hv"], scope="read", resource=resource)
assert rpc(client, _bearer(t), "ping")["result"] == {}
r = renew(app, t)
assert rpc(client, _bearer(r.json()), "ping")["result"] == {}
# one for another server is refused, renewed or not, and the app is told where to sign in for this one
app, t = _grant(client, env["hv"], scope="read", resource="https://elsewhere.example/mcp")
r = client.post("/mcp", headers=_bearer(t), json={"jsonrpc": "2.0", "id": 1, "method": "ping"})
assert r.status_code == 401 and "oauth-protected-resource/mcp" in r.headers["www-authenticate"]
r = renew(app, t)
assert client.post("/mcp", headers=_bearer(r.json()), json={"jsonrpc": "2.0", "id": 1, "method": "ping"}).status_code == 401
assert client.get("/api/v1/auth/me", headers=_bearer(r.json())).status_code == 200 # the check is the MCP server's


def test_the_transport(client, env):
h = env["h"]
post = lambda body, **hd: client.post("/mcp", headers={**h, **hd}, content=body if isinstance(body, str) else json.dumps(body)) # noqa: E731
Expand All @@ -89,6 +109,14 @@ def test_the_transport(client, env):
r = post([{"jsonrpc": "2.0", "id": 1, "method": "ping"}, {"jsonrpc": "2.0", "method": "notifications/initialized"}])
assert r.json() == [{"jsonrpc": "2.0", "id": 1, "result": {}}]
assert post([]).status_code == 400
assert post([{"jsonrpc": "2.0", "id": i, "method": "ping"} for i in range(mcp.MAX_BATCH)]).status_code == 200
r = post([{"jsonrpc": "2.0", "id": i, "method": "ping"} for i in range(mcp.MAX_BATCH + 1)])
assert r.status_code == 400 and r.json()["error"]["code"] == -32600
# too large: said by Content-Length, or found while reading one sent in chunks (which has none), never read whole
big = b" " * (mcp.MAX_BODY + 1)
assert post(big.decode()).status_code == 413
r = client.post("/mcp", headers=h, content=iter([b'{"jsonrpc": "2.0", "id": 1, "method": "ping"}', big]))
assert r.status_code == 413 and r.json()["error"]["code"] == -32600
# JSON-RPC errors
assert post("{nope").json()["error"]["code"] == -32700
assert post({"id": 1, "method": "ping"}).json()["error"]["code"] == -32600
Expand Down Expand Up @@ -224,6 +252,7 @@ def test_entities_and_the_graph(client, env, monkeypatch):

e = tool(client, h, "get_entity", entity_id=dyno["entity_id"], mentions=2)
assert e["name"] == "Dyno Therapeutics" and e["mentions"] == 4 and e["next_mentions_offset"] == 2
assert tool_error(client, h, "get_entity", entity_id=dyno["entity_id"], mentions_offset=10001).startswith("mentions_offset")
assert {m["name"] for m in e["mentioned_most_by"]} == {"Alice", "Bob", "Carol"}
line = e["lines"][0]
assert line["recording_id"] in (ep1, ep2) and "Dyno Therapeutics" in line["text"]
Expand Down
Loading