One plugin server serves every app in the session
Status: accepted
A Claude Code session is often started in a folder that holds several Rails apps (work/shop, work/admin, a monorepo's apps/*). The plugin's server entry is one fixed command line (ADR-0011), and one process serves one app: the booted tier is one Rails app per process, and the gem keeps its configuration, tier and caches in process globals. Before this, such a session got a refusal with no tools, and the model fell back to guessing.
Decision
- Where the session target (
AppRoot.target) is a folder of several apps, the plugin'sserveis a router,WorkspaceServer. It answers the handshake andtools/listitself, before any app's server starts, so the connect never waits on a boot. It lists each built-in tool once, with one more required argument,app, whose values are the apps' names (Install::Workspace.server_nameswithout the prefix). - A call's
apppicks the app. The router takes the argument out and hands the call to that app's own server: the binary'sserve --app-path <root>, started as a child in the app's folder at the first call that names it, and kept for the session. The child starts as therubyonPATHthere, so a shim version manager picks the app's Ruby (the router's own Ruby where norubyis onPATH), and runs the newest copy of the gem that Ruby has; a Ruby with none says so and names thegem installto run. The child does all it does for one app: the hand-off to the app's bundled copy, the boot or the static tier,skip_tools. A call naming no app it serves, a call whose child stops, and a call the router itself fails on are answered as a tool error, the second with the child's last lines read once it has exited, so the router never goes down with an app and never leaves a call unanswered. A child that stopped is dropped, and the app's next call starts it again. - Once a child has started, its own
tools/listreplaces what was assumed for its app: an app's custom tools join the list, a tool itsskip_toolsor an older copy lacks leaves that app out of the tool'sappvalues, and a tool whose arguments differ there gets an entry of its own,<tool>_<app>. The router then sendsnotifications/tools/list_changed, which Claude Code answers by reading the list again. The first list is built from each app's settings read without a boot,rails_get_config's sections included, so it matches what the app's server serves; a call for a tool or a section those settings turn off is answered at once, before the app's server starts. A call to a tool the app's server does not serve names the app, the version it runs once known, and itsskip_toolsas the other cause. Every listed name is cut, with a hash, to what Claude Code's 128-character limit onmcp__plugin_rails-ai-context_rails-ai-context__<tool>leaves. - Resources name the app in the URI,
rails-ai-context://apps/<app>/...(.../schema,.../models/{name}), and a read goes to that app's child as the URI the app's own server serves. A child'snotifications/resources/list_changed(live reload) goes on to the client; its log line reaches the router's log on the child's stderr. Anotifications/cancelledis not passed on: a child's stdio transport reads its next line only once the call in hand has answered. The router drops a call it has not yet sent to its child (one waiting on the app's start), which then gets no answer. A request an app's server makes of the client mid-call (sampling, elicitation, roots) is answered with an error at once, so its call goes on. The instructions name the apps that fit under Claude Code's 4096-character cut and then how many more; each tool'sapplists them all. - The handshake answers with the client's protocol revision where the router knows it, else the newest it knows, as the refusal does.
- The command line stays the one fixed line. The router is a branch of
servethat the plugin's script reaches by settingRAILS_AI_CONTEXT_PLUGIN=1; anallowedMcpServersentry admits it as it admits the single-app server. - The router does not depend on MCP roots. Claude Code does send them, but the installed mcp gem marks
roots/listdeprecated as of protocol 2026-07-28, the gemspec'smcp >= 0.13floor cannot ask for them, and the start folder's walk finds every folder shape seen. The router speaks plain JSON-RPC over stdio and needs nothing from the mcp gem but each tool's ownto_h. - The single-app session keeps the direct serve, with no router process between, but for one case: where the serve hands the app to its bundled copy, the plugin's process stays in front of that copy as a proxy (
ChildServer.proxy) that passes every line on unchanged, so a copy older than the refusal, which exits where it cannot serve, still leaves a connected server. A copy that stops before it answersinitializegets the refusal handshake with what it printed; one that stops later leaves an error naming that for each request still to answer. The router's children and the proxy share one module,ChildServer.
Consequences
Every app in the folder is reachable from one server, with no per-folder init and no turning the plugin off there. A folder whose committed settings turn the plugin on gets no workspace entries for Claude Code from init, as one app's folder gets none, and ClaudeCodeSettings counts a session there among those that run the plugin for each app.
The costs: the first call for an app waits for its boot (the typed boot limit, 60 seconds or RAILS_AI_CONTEXT_BOOT_TIMEOUT, then the static tier: no client waits on a child's handshake, so the router sets RAILS_AI_CONTEXT_ROUTED=1 for it), where a single-app session pays it before the handshake. Every app's server stays up until the session ends. Until an app's server has started, the list assumes the built-in tools its settings leave on, read without a boot, so its custom tools appear only after its first call, and a first call that used the built-in arguments where the app's copy takes others is told the name to call instead. A child whose Ruby is chosen another way than by a shim (rvm, chruby) runs the Ruby of the router's PATH. An app whose server keeps failing is started again at each call that names it.
Alternatives not taken
- Per-app tool names for every tool (
shop__rails_get_schema): 35 tools times N apps in one list, every app booted before the handshake answers, and names that run toward Claude Code's 128-character limit. Only a tool whose arguments differ in one app gets a name of its own. - One process serving several apps from source: covers the static tier only, and every reader of the process globals (configuration, tier, the shared caches, the working directory) would have to take an app.
- MCP roots as the list of apps: deprecated in the protocol, absent from the mcp gem's floor, and not needed.
- The hook telling the model to pass
--app-path: the model would be told about apps its tools cannot reach. It stays only for a gem older than 5.38.0, which has no router.