Skip to content

feat(extensions): run stdio MCP servers in a sandboxed runner - #304

Merged
adeelahmad merged 8 commits into
mainfrom
claude/project-thread-ks9sah
Oct 14, 2026
Merged

adeelahmad merged 8 commits into
mainfrom
claude/project-thread-ks9sah

Conversation

@adeelahmad

@adeelahmad adeelahmad commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

Requested by Adeel · project thread

Description

Before: Lens could use only MCP servers on the network (HTTP). Servers that run as a program (stdio, usually npx or uvx), which are most of the servers in marketplaces, were left out.

After: they run in the MCP runner, a new opt-in container (COMPOSE_PROFILES=mcp, or docker compose --profile mcp up -d). Admins add a stdio server as an mcp extension with command, args and env, just as Claude's .mcp.json describes it. A plugin's stdio servers are installed with it when an admin installs the plugin, except servers whose program ships inside the plugin folder.

The runner container is the sandbox:

  • It has no Lens data, keys or database.
  • It runs as a non-root user with every capability dropped, no-new-privileges, a read-only image, and memory and process limits.
  • It sits on a network of its own that only the backend joins, plus internet access so npx and uvx can fetch servers.
  • Each server gets an empty home folder and only the environment its extension gives it.
  • Lens reaches it over HTTP with a token the runner writes to a volume that only the two containers share.

A server starts on first use, is initialized once, and stops after 15 idle minutes. If it crashes, the error comes back to the caller and the next use starts it again.

mcp-runner/runner.py is our own code, using only the Python standard library (about 250 lines). The existing bridges either take a fixed config at startup (mcp-proxy) or run one server per process (supergateway). Lens needs servers registered while it runs and the client's initialize answered from one long-lived process.

Brought up to date with main on 2026-10-14 (merge commit; the compose files keep both the mcp and styletts2 services), with the runner recorded in threat-model.md (Assistant family and the dependency table), a CHANGELOG entry and the refine-later list in DEVLOG.

Motivation and Context

This follows #276. It closes the "MCP servers that run as a program aren't run" gap, since most marketplace MCP servers are stdio.

Steps to reproduce (if appropriate):

tests/api/test_mcp_servers.py runs the real runner against a fake stdio server: it lists tools, calls one, reuses the same process, and restarts it after a crash. The new MCP runner workflow builds the image, runs it hardened as compose does, and calls real servers from npm (@modelcontextprotocol/server-memory) and PyPI (mcp-server-time).

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change; ! in the title)

Checklist:

  • The title is a Conventional Commit.
  • My code follows the code style of this project (make hooks checks it on commit).
  • I added or updated tests.
  • My change requires documentation updates, and I have updated docs/ accordingly.
  • Users need more than the title to understand it, so I wrote it under ## Unreleased in CHANGELOG.md.

Done questions (AGENTS.md)

  • Goal: stdio MCP servers run, from an admin's extension or a plugin; merged on green CI.
  • Agents: admins add them through the extensions API and the assistant's setup tools; their tools reach the assistant as <server>__<tool>.
  • Zero setup: n/a for the default install, which is unchanged; the runner is opt-in and needs COMPOSE_PROFILES=mcp (refine later: turn it on from Settings through the machine agent, as monitoring does).
  • Fewest clicks: a server is one extension with its command; a plugin brings its servers with it.
  • Configurable: no new setting; the extension holds the command, args and env.
  • Light: off by default; the runner image is only pulled and built with the mcp profile.
  • Private and secure: the runner holds no Lens data or keys, is unprivileged and read-only, token-gated, on its own network; threat model updated.
  • Cost: no model calls; mcp.list and mcp.call go through the activity ledger as before.
  • User decides: only admins add servers; tools a server doesn't mark read-only ask for approval.
  • Upgrades: n/a, no stored-data change (an mcp spec gains optional command, args, env).
  • Honest: docs say it's opt-in and Docker-only for now.
  • Tests, docs (assistant.md, threat model, CHANGELOG, DEVLOG); no generated file changes.
  • Open: MCP, standard library only; the image uses Node and uv (MIT/Apache).
  • Reported in the project thread; refine-later items in DEVLOG.

🤖 Generated with Claude Code

https://claude.ai/code/session_0188zd7Y9m6tdENwXQyhCSH2

MCP servers that run as a program (npx, uvx) run in the MCP runner, an
opt-in container (COMPOSE_PROFILES=mcp) with none of Lens's data or keys,
no capabilities, a read-only image and a network shared only with the
backend. Admins add them as mcp extensions with command/args/env, and a
plugin's stdio servers come along when an admin installs it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CsyA2Kuhsnhzz2HjkD3zED
@adeelahmad adeelahmad self-assigned this Oct 10, 2026
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CsyA2Kuhsnhzz2HjkD3zED
Records the runner as new surface (Assistant family and the dependency
table) and fixes the marketplace docstring that still said plugins bring
network MCP servers only.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0188zd7Y9m6tdENwXQyhCSH2
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0188zd7Y9m6tdENwXQyhCSH2
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0188zd7Y9m6tdENwXQyhCSH2
@adeelahmad
adeelahmad merged commit 586bf53 into main Oct 14, 2026
19 checks passed
@adeelahmad
adeelahmad deleted the claude/project-thread-ks9sah branch October 14, 2026 10:36
adeelahmad pushed a commit that referenced this pull request Oct 14, 2026
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014pKRz6HkdQ7hTqEbpnyhYo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants