feat: start MCP servers on first call and keep stored tool lists fresh #43

Merged
marti merged 2 commits from feature/lazy-upstream-start into develop 2026-11-07 13:36:59 +01:00
Owner

Summary

Agents' tools/list no longer starts a runner process per server. Lazy servers (the new default) answer from the tools stored at their last listing and start on the first tools/call.

 tools/list (gateway)
   for each ready server
-    connect (spawn process) and list tools
+    live connection?           -> its tools
+    lazy and stored list?      -> stored tools, start nothing
+    otherwise                  -> connect and list (as before)
 tools/call
   connect if needed (spawns on first call)

Stored lists stay current through ToolRefresher:

user saves values / finishes per-user OAuth  -> list that user's process now
POST /api/me/servers/:id/check ("Check now") -> same, awaited
every TOOL_REFRESH_INTERVAL_HOURS (12)       -> shared keys + per-user keys of
                                                users active on /mcp in 14 days,
                                                2 at a time, process stops after
 apps/api/src/
 ├── db/schema.ts                     # + mcp_servers.start_mode, + upstream_tool_lists
 ├── services/upstream/
 │   ├── index.ts                     # listTools(ctx, stored), refresh(ctx), store every listing
+│   ├── tool-lists.ts                # load/save/forget stored lists, ToolCheck view
+│   └── refresh.ts                   # ToolRefresher (setup, Check now, schedule)
 ├── services/gateway/tools.ts        # lazy servers read stored lists
 ├── services/admin/{servers,install}.ts  # start mode, health, forget lists on config change
 └── routes/me/servers.ts             # + POST /api/me/servers/:id/check
 apps/web/
 ├── admin/servers/OverviewTab.tsx    # + Startup section (switch, last listing, user counts)
 └── portal/ServerPage.tsx            # + ConnectionCheck (last start, error, Check now)
  • upstream_tool_lists holds one row per process key: user_id null for a shared process, one row per user for a per-user server. A per-user row is shown only to that user. The shared server_tools catalog is unchanged, and per-user tools still never go into it.
  • A server's stored lists are deleted when its package, installed version, args, endpoint, OAuth settings or variables change.
  • New env vars: TOOL_REFRESH_INTERVAL_HOURS, TOOL_REFRESH_CONCURRENCY, TOOL_REFRESH_ACTIVE_DAYS (documented in .env.example and docs/configuration.md).

Evidence

  • Before: every tools/list attached one runner process per ready server, so connecting a client spawned all of them.
    After: apps/api/test/lazy-start.test.ts (10 tests):
invalidate every process, then a second client lists tools
  lazy server:      attaches unchanged, tools still listed
  per-user server:  attaches unchanged, tools still listed
  eager server:     attaches + 1
  first tools/call: lazy server attaches + 1
user saves values  -> their row appears with 4 tools, env = their own value
runDue()           -> 3 keys (2 shared + Alice); Bob (never used /mcp) skipped; 0 when rerun

The full CI script (nix develop -c ./scripts/ci.sh) passes: lint, typecheck, API 325, runner 46, web 149, shared 5, build, and npm audit with 0 vulnerabilities.

Merge Danger

Door: two-way

The migration only adds things: an enum, a column with a default, and a table. Reverting the code leaves them unused and harmless.

Blast Radius: every server

  • Every existing server becomes lazy. Its first tool call is slower (cold start), and its tool list can be up to one refresh interval old. An admin can switch a server back to eager on its overview.
  • The scheduled refresh briefly starts up to 2 processes at a time every 12 hours.
  • trail check flags app.ts, config.ts, schema.ts and upstream/index.ts against old learnings (hand-written or admin tools on /mcp, catalog re-enabling). They are keyword matches. No MCP tools are added, and stored lists never write enabled; the gateway still applies the admin's tool switch to them (tested).

🤖 Generated with Claude Code

## Summary Agents' `tools/list` no longer starts a runner process per server. Lazy servers (the new default) answer from the tools stored at their last listing and start on the first `tools/call`. ```diff tools/list (gateway) for each ready server - connect (spawn process) and list tools + live connection? -> its tools + lazy and stored list? -> stored tools, start nothing + otherwise -> connect and list (as before) tools/call connect if needed (spawns on first call) ``` Stored lists stay current through `ToolRefresher`: ```text user saves values / finishes per-user OAuth -> list that user's process now POST /api/me/servers/:id/check ("Check now") -> same, awaited every TOOL_REFRESH_INTERVAL_HOURS (12) -> shared keys + per-user keys of users active on /mcp in 14 days, 2 at a time, process stops after ``` ```diff apps/api/src/ ├── db/schema.ts # + mcp_servers.start_mode, + upstream_tool_lists ├── services/upstream/ │ ├── index.ts # listTools(ctx, stored), refresh(ctx), store every listing +│ ├── tool-lists.ts # load/save/forget stored lists, ToolCheck view +│ └── refresh.ts # ToolRefresher (setup, Check now, schedule) ├── services/gateway/tools.ts # lazy servers read stored lists ├── services/admin/{servers,install}.ts # start mode, health, forget lists on config change └── routes/me/servers.ts # + POST /api/me/servers/:id/check apps/web/ ├── admin/servers/OverviewTab.tsx # + Startup section (switch, last listing, user counts) └── portal/ServerPage.tsx # + ConnectionCheck (last start, error, Check now) ``` - `upstream_tool_lists` holds one row per process key: `user_id` null for a shared process, one row per user for a per-user server. A per-user row is shown only to that user. The shared `server_tools` catalog is unchanged, and per-user tools still never go into it. - A server's stored lists are deleted when its package, installed version, args, endpoint, OAuth settings or variables change. - New env vars: `TOOL_REFRESH_INTERVAL_HOURS`, `TOOL_REFRESH_CONCURRENCY`, `TOOL_REFRESH_ACTIVE_DAYS` (documented in `.env.example` and `docs/configuration.md`). ## Evidence - **Before:** every `tools/list` attached one runner process per ready server, so connecting a client spawned all of them. **After:** `apps/api/test/lazy-start.test.ts` (10 tests): ```text invalidate every process, then a second client lists tools lazy server: attaches unchanged, tools still listed per-user server: attaches unchanged, tools still listed eager server: attaches + 1 first tools/call: lazy server attaches + 1 user saves values -> their row appears with 4 tools, env = their own value runDue() -> 3 keys (2 shared + Alice); Bob (never used /mcp) skipped; 0 when rerun ``` The full CI script (`nix develop -c ./scripts/ci.sh`) passes: lint, typecheck, API 325, runner 46, web 149, shared 5, build, and `npm audit` with 0 vulnerabilities. ## Merge Danger **Door:** two-way The migration only adds things: an enum, a column with a default, and a table. Reverting the code leaves them unused and harmless. **Blast Radius:** every server - Every existing server becomes `lazy`. Its first tool call is slower (cold start), and its tool list can be up to one refresh interval old. An admin can switch a server back to eager on its overview. - The scheduled refresh briefly starts up to 2 processes at a time every 12 hours. - `trail check` flags `app.ts`, `config.ts`, `schema.ts` and `upstream/index.ts` against old learnings (hand-written or admin tools on `/mcp`, catalog re-enabling). They are keyword matches. No MCP tools are added, and stored lists never write `enabled`; the gateway still applies the admin's tool switch to them (tested). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Until now every tools/list connected to every ready server, so one client
connecting started a runner process per server (per user for per-user
servers) for at least UPSTREAM_IDLE_TIMEOUT_SECONDS.

- mcp_servers.start_mode (default lazy): tools/list answers from the live
  connection or from upstream_tool_lists and starts nothing; the process
  starts on the first tools/call. eager keeps the old behaviour.
- upstream_tool_lists stores each process key's last listing and check:
  shared keys, and per-user keys served only to that user. The shared
  catalog is unchanged, and per-user tools never go into it.
- ToolRefresher lists a user's key right after they save their values or
  finish an OAuth sign-in, on POST /api/me/servers/:id/check, and on a
  schedule (TOOL_REFRESH_INTERVAL_HOURS, _CONCURRENCY, _ACTIVE_DAYS).
- Portal and admin views show the last check; the admin can switch the
  start mode per server.

trail check flags app.ts, config.ts, schema.ts and upstream/index.ts as
bringing back hand-written or admin tools on /mcp, and catalog re-enables.
Those are keyword matches: no MCP tools are added, and stored lists never
write `enabled` (the gateway still applies the admin's switch to them,
covered in lazy-start.test.ts).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat(web): start mode switch, tool check status and Check now
All checks were successful
CI / check (pull_request) Successful in 6m14s
dea523fbf0
The admin overview gets a Startup section (start on first call, last tool
listing, users' check counts). The portal server page shows the last start
of the user's own process of a per-user server, its error, and a Check now
button, and polls while a check runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
marti merged commit 3054a63ca0 into develop 2026-11-07 13:36:59 +01:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
marti/mcphub!43
No description provided.