A workspace's MCP entries name their app by a relative path
Status: accepted
rails-ai-context init run in a folder of apps (a workspace, see GLOSSARY.md) writes one server per app into the folder's own MCP configs (#429). Those files may be committed, so each entry has to find its app on any machine, and an AI tool gives a stdio server nothing to find it with but the command line, the environment and the directory it starts the server in.
What the tools do
Checked against each tool's documentation and source in October 2026:
| Tool | Starts the server in | Names the config's folder |
|---|---|---|
Claude Code (.mcp.json) |
the folder it was launched in; it also reads a .mcp.json above that folder |
no; no cwd key either |
Codex CLI (.codex/config.toml) |
its session directory | no; a cwd key, itself relative to the session directory |
OpenCode (opencode.json) |
the folder it was opened in | no; a cwd key only from v1.17.4, and older versions reject unknown keys |
VS Code (.vscode/mcp.json) |
the workspace folder | ${workspaceFolder} |
Cursor (.cursor/mcp.json) |
the editor (3.27): the project's folder; the agent CLI (2026.10.22): the folder it runs in |
no; the agent CLI passes ${workspaceFolder} to the server as literal text |
Copilot CLI (.github/mcp.json) |
the folder it runs in (not documented; Claude Code's .mcp.json entries rely on the same) |
no |
Decision
--app-pathand an in-Gemfile app'sBUNDLE_GEMFILEare written relative to the workspace. Where every client of the config expands a name for its folder (VS Code:AiTool'sfolder_variable), they start from that name; elsewhere they are bare relative paths, which those tools resolve against the folder they were started in. An absolute path would hold only on the machine that wrote it. Cursor's entries started from${workspaceFolder}until theagentCLI was found to pass it on unexpanded; an entry written that way is still read as the gem's and is rewritten by the nextinit.- Each app keeps its own install form: the bare binary for a standalone app,
bundle execfor an in-Gemfile one, decided from that app's own Gemfile.lock (or its Gemfile, before the bundle is installed) rather than the process's bundle. - A re-run writes the current set: an entry under a name the gem gives an app in the folder (its folder name or its path, never a numbered one) is dropped when that app's folder is gone, or when a twin's arrival renamed it. A folder this machine lacks reads as gone: the gem cannot tell an app removed from one never checked out. An entry counts as the gem's by its name and by running
rails-ai-context serve, or, under the bare name every version has written, by running a command at all; an entry with no command (an HTTP one), a second entry named by hand for an app, a numbered one (as likely made by hand), one naming its app through a variable the tool expands, and one naming an app outside the folder are left as somebody's own. So is one of the gem's that starts its server in a form the gem does not write (through Docker), which the write names in its note. - An in-Gemfile app's
BUNDLE_GEMFILEnames the Gemfile its bundle reads: its own, by the name it has in the app even when it links elsewhere, since Bundler names the lockfile after the path it is given; else the one itsconfig/boot.rbnames, which is how a monorepo's apps share one bundle; else the onebundle execrun inside the app would find. With none of these the entry names none. - A config the gem cannot write back faithfully - one JSON does not parse, which VS Code and OpenCode accept with trailing commas, one whose comments a rewrite would drop, or one that is not UTF-8 - is left as it is, with the entry to add by hand, said where the install speaks. A folder's config is the likelier to be kept by hand.
- Each entry is
rails-ai-context-<app folder>and announces<app folder>-rails-ai-context, through theRAILS_AI_CONTEXT_SERVER_NAMEenvironment variable rather than a flag: an app whose bundle pins an older gem ignores an unknown variable and starts, where an unknown flag would stop it. The variable only takes the place of the default name, so aserver_namethe app configured wins. VS Code names every tool after the announced name, sanitised and cut to 13 characters, so a name that starts with the gem's would give every app's tools the samemcp_rails-ai-cont_prefix and leave the model unable to tell them apart. Names are capped at 30 characters (a hash keeps a longer one unique): Cursor drops a tool whose server and tool names together pass 60, Codex up to v0.100 cappedmcp__<server>__<tool>at 64, and the longest built-in tool name is 27.
Consequences
The entries work when the tool is started in the workspace folder, which is the setup they are written for. A tool started inside one of the apps that still reads the workspace's config (Claude Code, Codex, OpenCode, Copilot CLI) starts each server there, where a relative path misses. The binary then names the folder the path was written for instead of guessing a different app; an in-Gemfile entry fails earlier, in Bundler, before the gem runs. An app opened on its own gets its own config from init run inside it.
Every server in a workspace runs under the Ruby the tool resolves in the workspace folder, which a version manager picks by that folder, not by the app. init warns when an app declares another; a standalone app that cannot boot under it answers from the static tier, and an in-Gemfile entry may not start.
Alternatives not taken
- Absolute paths: correct on one machine, wrong in every clone.
- A
cwdkey per entry: Claude Code has none, OpenCode's breaks its older versions, and Codex's is relative to the same directory a bare path already is. - Walking up for a relative
--app-paththat misses: it would make the binary's--app-pathmean different things in different directories, and would still leavebundle execentries failing before the gem runs. - Re-launching an in-Gemfile app's server from inside the app (the global binary resolving the app, then
execingbundle execthere): it fixes the Ruby choice, but needs the binary installed outside every bundle, and cannotexecin place on Windows.