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
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
versions and every version's messages, and `PUT /api/v1/chats/<id>/head` switches between them; the model reads
only the version showing. The web app's switcher and Regenerate button are in progress. Existing conversations are
upgraded on the next start (`chat-tree`) ([Versions](docs/assistant.md)).
- **Add an MCP server with a form, or paste its config.** Extensions → Add MCP server (admins) takes an address and
its headers, or a command with its arguments and environment, or reads a config pasted from Claude (`.mcp.json`) or
VS Code, one server or many; Test lists its tools before it's saved. Tokens and keys in headers and env are now
sealed and never shown again (manifests say `••••`), and an upgrade step seals the ones saved before. Each server's
tools have a switch and "Asks first", kept in its manifest
([Adding an MCP server](docs/assistant.md#adding-an-mcp-server)).
- **Describe an automation in words.** `POST /api/v1/automations/draft` asks the model once to turn a sentence into
a draft automation to try and save, and says what didn't fit and what it couldn't express
([Describe it in words](docs/automations.md#describe-it-in-words)).
Expand Down
36 changes: 33 additions & 3 deletions docs/assistant.md
Original file line number Diff line number Diff line change
Expand Up @@ -248,9 +248,10 @@ shared with namespaces (admins can share with everyone), and switched on or off
- **MCP server** (admins add them): a server that speaks the Model Context Protocol over Streamable HTTP, at the
address an admin gives (this machine and the local network included, as for the model's address), with the headers
it needs (a token). Lens lists its tools when it's saved, and the assistant calls them as `<server>__<tool>`: one the
server marks read-only answers at once, the others ask for approval. A server that runs as a program (stdio:
`command`, `args` and `env` instead of an address, as in Claude's `.mcp.json`, usually `npx` or `uvx`) runs in the
MCP runner, below.
server marks read-only answers at once, the others ask for approval, and an admin switches each on or off and says
which ask first ([Adding an MCP server](#adding-an-mcp-server)). A server that runs as a program (stdio: `command`,
`args` and `env` instead of an address, as in Claude's `.mcp.json`, usually `npx` or `uvx`) runs in the MCP runner,
below.
- **Plugin**: a bundle of tools, skills, hooks and MCP servers, shared and switched off as one.

Make one however suits you:
Expand Down Expand Up @@ -300,6 +301,35 @@ the network (`.mcp.json`) come along when an admin installs it, and those that r
runner is on (ones that run a program shipped inside the plugin are left out). Repositories are read from GitHub or GitLab (or the archive link) through the same guard as web
tools: public addresses only.

### Adding an MCP server

On **Extensions**, **Add MCP server** (admins) takes a name and either the server's address with the headers it needs,
or the command it runs as with its arguments and environment. **Paste a config** reads the JSON other apps keep their
servers in, one server or many: Claude's `.mcp.json` (or `mcpServers` in its settings), VS Code's `mcp.json`
(`servers`), or a server on its own as its README gives it. A server without a name is named after its package or its
address (`@modelcontextprotocol/server-github` is `github`), and values written as `${NAME}`, which those apps fill in
from their own settings, are pointed out to fill in. Servers on the older SSE transport are left out with a note.
**Test** asks the server for its tools before anything is saved, and Enter adds it. Over the API:
`POST /api/v1/extensions/mcp/read` reads a config (nothing is reached), `POST /api/v1/extensions/mcp/test` lists a
server's tools without saving it, and `POST /api/v1/extensions` saves it as an extension of kind `mcp`.

Header and environment values whose names say they carry a credential (Authorization, API keys, tokens, secrets,
passwords, cookies, sessions) are sealed when the server is saved, with the server's key (as notification targets and
sources are, since an MCP server belongs to the whole install rather than a namespace), bound to the extension, the
value's name and where it goes: the address's scheme, host and port, or the command with its arguments. They're opened
only to reach the server and never shown again: the page, the API and the manifest give the name and `••••`. Saving a
manifest with `••••` keeps the value saved before, unless the server now goes somewhere else (another host, or another
command or package), when it asks for the value again, and a sealed value copied into another extension doesn't open.
Other headers (`X-Team: blue`) stay as they are, and so does a secret written into the address or the arguments, so
put tokens in headers or the environment.

Each server's page lists its tools with a switch and **Asks first**. A tool the server marks read-only runs at once and
the others ask, unless an admin says otherwise; the choices are kept in its manifest (`off`, the tools switched off,
and `ask`, `{tool: true or false}` where it differs from the server's hint), stay when its tools are listed again, and
each change is a new version (`PATCH /api/v1/extensions/{id}/tools` with `{tool, on, ask}`). Whatever the switch says,
an MCP tool still asks first after the conversation read outside text, as every tool that sends to another host does
([Third-party content and prompt injection](#third-party-content-and-prompt-injection)).

### The MCP runner

MCP servers that run as a program run in a container of their own, the MCP runner
Expand Down
2 changes: 2 additions & 0 deletions docs/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,8 @@ The steps so far, in the order they run:
(`chat_message`) gets the one before it as its `parent`, and the conversation (`chat`) its last message as its
`head`. Only conversations without a `head` are touched, so it's safe to run twice; until it has run, a conversation
without a `head` is read as one line, and saved as one before anything is added to it.
* `mcp-sealed-secrets`: the tokens and keys MCP servers kept in plain text in their headers and env are sealed,
in every version ([Adding an MCP server](assistant.md#adding-an-mcp-server)); sealed ones are left as they are.

To add a step:

Expand Down
5 changes: 3 additions & 2 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ and sees exactly what that person sees: their namespaces, the collections they w
those open. Its tools read, except the few listed under [Tools](#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](assistant.md#extending-the-assistant-tools-skills-hooks-and-plugins)).
It works the other way too: Lens's own assistant calls the tools of MCP servers an admin adds, as extensions, by a
short form or a config pasted from another app, with their tokens sealed
([Adding an MCP server](assistant.md#adding-an-mcp-server)).

## Connecting

Expand Down
35 changes: 33 additions & 2 deletions fastapi_backend/app/api/v1/routes/extensions.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
from fastapi import APIRouter, HTTPException, Request

from app.api.deps import Acl, Cfg, CurrentUser, Db, Principal, Writer, domain_errors
from app.domain import ai_tools, auth, extensions, marketplace
from app.domain import ai_tools, auth, extensions, marketplace, mcp_servers
from app.schemas.common import Created, Ok
from app.schemas.extensions import (
Extension,
Expand All @@ -26,6 +26,11 @@
Kind,
ManifestCheck,
ManifestChecked,
McpConfig,
McpConfigText,
McpServerTools,
McpServerTry,
McpToolSwitch,
)
from app.schemas.templates import VersionSaved

Expand Down Expand Up @@ -93,6 +98,22 @@ def import_archive(body: ExtensionImportArchive, user: Writer, db: Db) -> Extens
return ExtensionImportPreview(**out) if body.preview else ExtensionImported(**out)


@router.post("/mcp/read")
def read_mcp_config(body: McpConfigText, user: CurrentUser) -> McpConfig:
"""The MCP servers in a config pasted from another app (Claude's .mcp.json, VS Code's mcp.json), ready to add: each
as an MCP extension keeps it, and what was left out and why. Nothing is reached or saved."""
with _errors():
return McpConfig(**mcp_servers.read(body.text))


@router.post("/mcp/test")
def test_mcp_server(body: McpServerTry, user: Writer, db: Db) -> McpServerTools:
"""Ask an MCP server for its tools without saving it (admins). With `extension`, values sent as •••• are that
server's saved ones."""
with _errors():
return McpServerTools(tools=extensions.try_mcp(db, me(user), body.spec, body.extension))


@router.get("/{eid}")
def get_extension(eid: int, user: CurrentUser, db: Db, version: int | None = None) -> ExtensionDetail:
"""One version (default: the current one), as a manifest too, and the list of versions."""
Expand All @@ -108,6 +129,15 @@ def create_extension_version(eid: int, body: ExtensionVersionCreate, user: Write
return VersionSaved(version=n)


@router.patch("/{eid}/tools")
def switch_mcp_tool(eid: int, body: McpToolSwitch, user: Writer, db: Db) -> VersionSaved:
"""Switch one of an MCP server's tools on or off, or say whether it asks first (admins): a new version."""
with _errors():
n = extensions.switch_tool(db, me(user), eid, body.tool, on=body.on, ask=body.ask)
auth.audit(db, user.as_audit(), "extension.save", f"extension:{eid}", {"version": n, **body.model_dump(exclude_none=True)})
return VersionSaved(version=n)


@router.patch("/{eid}")
def update_extension(eid: int, body: ExtensionUpdate, user: Writer, db: Db) -> Ok:
"""Its title, description, who sees it, and whether it's switched on."""
Expand All @@ -131,7 +161,8 @@ def test_extension(eid: int, body: ExtensionTest, user: Writer, acl: Acl, db: Db
"""Try one of its tools with these arguments, switched on or not. A tool that changes something really runs, so it
needs `confirm`."""
with _errors():
g = extensions.visible_one(db, me(user), eid)
extensions.visible_one(db, me(user), eid)
g = extensions.get(db, eid) # as saved: what's shown hides an MCP server's secrets
name = body.tool or (g["name"] if g["kind"] == "tool" else None)
t = next((it for it in extensions.tool_items(g) if it["name"] == name), None)
if not t:
Expand Down
Loading
Loading