AI Tool Setup
Per-editor setup for Claude Code, Cursor, Copilot, OpenCode, and Codex CLI.
TipRather let your AI tool do it? Paste one of the copy-paste prompts into it.
Table of Contents
- Which path is right for you?
- Claude Code
- Cursor
- GitHub Copilot
- OpenCode
- Codex CLI
- A folder of apps
- Ruby in Docker
- Other MCP clients
- Verify MCP is connected
- HTTP Transport
- Regenerating context files
Which path is right for you?
flowchart TD
A[Start] --> B{Can you modify\nthe Gemfile?}
B -->|Yes| C[In-Gemfile]
B -->|No| D[Standalone]
C --> H{Which AI tools?}
D --> H
H -->|"Claude Code, Cursor, GitHub Copilot,\nOpenCode, Codex CLI, or all"| E{What should\nit write?}
E -->|"1 - default"| F[MCP config +\ncontext files]
E -->|"2 - no MCP server"| G[Context files only\nCLI mode]
E -->|"3 - keep your own files"| O[MCP config only]
style C fill:#27ae60,stroke:#1e8449,color:#fff
style D fill:#3498db,stroke:#2980b9,color:#fff
style F fill:#e67e22,stroke:#d35400,color:#fff
style G fill:#9b59b6,stroke:#8e44ad,color:#fff
Claude Code
Auto-setup (recommended)
rails generate rails_ai_context:install --tools claude --defaults # or run it bare and pick "Claude Code"
rails-ai-context init --tools claude --defaults # standalone
This creates:
.mcp.json- MCP config, read when a session starts in the folder; approve the server onceCLAUDE.md- Root context file. With Cursor, OpenCode or Codex CLI chosen too, it holds only@AGENTS.md, an import Claude Code expands at launch, andAGENTS.mdcarries the content.claude/rules/rails-schema.md- Schema rules (loaded when editing a schema dump or a migration of any of the app's databases).claude/rules/rails-models.md- Model rules (loaded when editingapp/models/).claude/rules/rails-components.md- Component rules (loaded when editingapp/components/orapp/views/components/, written only when the app has view components).claude/rules/rails-context.md- Project overview (always loaded), written only whengenerate_root_filesis off, since the root file states it otherwise.claude/rules/rails-mcp-tools.md- Tools guide: the protocol, the workflows and the rules, as the root file carries them (always loaded), written only whengenerate_root_filesis off
Keeping your own CLAUDE.md? Add --mcp-only and only .mcp.json is
written; every context file is left alone. See
CONFIGURATION.md.
Manual MCP config
If you need to configure manually, create .mcp.json:
{
"mcpServers": {
"rails-ai-context": {
"command": "bundle",
"args": ["exec", "rails-ai-context", "serve"]
}
}
}
This is what the generator writes for an in-Gemfile install. A standalone install has no bundle exec: the command is rails-ai-context and the args are ["serve"]. The same goes for the other tools below.
On Windows the command is cmd and "/d", "/c" go ahead of the args (["/d", "/c", "bundle", "exec", "rails-ai-context", "serve"]): a gem's executables there are batch files, which a client that starts its server without a shell does not run. The generator writes that form on Windows, and doctor names an entry written for the other platform; see GUIDE.md for teams on both.
As a plugin
The repository is also a Claude Code plugin marketplace. The plugin brings the
MCP server and, at the start of each session in a Rails app, the six rules the
context files carry. It writes no context files or MCP config, so it suits
a team that keeps its own CLAUDE.md; the install records it in
.claude/settings.json.
gem install rails-ai-context # the plugin runs the installed gem
claude plugin install rails-ai-context --marketplace crisnahine/rails-ai-context --scope project
In a session the second line is /plugin install rails-ai-context --marketplace crisnahine/rails-ai-context.
A Claude Code too old for --marketplace takes two steps:
/plugin marketplace add crisnahine/rails-ai-context, then
/plugin install rails-ai-context@rails-ai-context. Project scope records the
plugin in .claude/settings.json of the folder you run it in, so run it in the
app's folder; commit that file, and add the marketplace there too so a
teammate's Claude Code offers to install it:
{
"enabledPlugins": { "rails-ai-context@rails-ai-context": true },
"extraKnownMarketplaces": {
"rails-ai-context": { "source": { "source": "github", "repo": "crisnahine/rails-ai-context" } }
}
}
A teammate who has the committed setting runs claude plugin install
rails-ai-context --marketplace crisnahine/rails-ai-context --scope local,
which leaves the committed file as it is.
- Where it runs. Claude Code reads
.claude/settings.jsononly from the folder a session starts in, so project scope reaches sessions started in the app's folder. For sessions started in a folder inside the app, or in a monorepo's app folder from the repository's root, enable it with--scope local(the git repository'ssettings.local.json) or at user scope. The server then reads the app Claude Code was started in, the app above that folder, or the one app below it, as every command does. At user scope the plugin starts in every project; outside a Rails app its server connects with no tools and tells the session why. A monorepo's root whosebin/railsboots an app below it serves that app, and an engine whose code is all inlib/serves itstest/dummyorspec/dummyapp. On Windows the plugin serves one app per session: in a folder of several apps its server connects with no tools and names each app and the--app-pathcommand that runs its tools. Elsewhere a folder that holds several apps serves them all from one server (rails-ai-context 5.38.0 or later): every tool takes anappargument naming the app, the session-start rules list the names, and each app's own server starts at the first call that names it, as therubyonPATHin that app's folder. Where rbenv's, asdf's or mise's shims are onPATH, the shim picks that Ruby by the app's own.ruby-versionor.tool-versions, whatever folder the session started in or pinned: ahead of the first shims folder onPATH, the server leaves out each folder under the manager's ownversions/orinstalls/(where itsexecormise xput the session's Ruby) and keeps every other folder, such as a system Ruby's/usr/bin. It also leaves out the variables that name the session's version. rvm, chruby andmise activatewithout shims pick a Ruby only through a shell hook, which a server's child never runs, so there every app runs the session's Ruby; where an app's version file names another Ruby, the first answer for that app says so. An app whose shim picks another Ruby than the server's gets none of the server's gems, so it needs the gem installed for its own Ruby. The server asks the shim which Ruby it runs once per app, and again at the app's next server start after a version file changes: the app's own or a parent folder's, or the manager's global one (rbenv'sversion, the home folder's.tool-versions, mise's global config). Once it has started, the list follows that app's own tools (its custom tools, itsskip_tools, an older bundled copy's arguments, under a name ending in the app's) and Claude Code reads it again. An app whose server stops is started again at its next call, and the failed call says what it printed last. Resources name the app in the URI (rails-ai-context://apps/<app>/schema). Each answer's paths are relative to its app's folder, which the server's instructions name. An older gem serves one app, and in a folder of several it says to start Claude Code in one of them and names therails-ai-context --app-path <app> tool <name>commands meanwhile. On macOS and Linux a local setting written at a git repository's root reaches every session in that repository, the apps' too. On Windows, and where the repository's root is your home folder or belongs to another user, a local setting reaches only sessions started in the folder it was written in. Whereinitat a repository's root wrote an app's own.mcp.json, which sessions started in the app read, a--scope localinstall that reaches those sessions runs the plugin beside it;doctornames the one to turn off. - The gem comes first. The plugin needs rails-ai-context 5.38.0 or later,
installed for the
rubyon Claude Code'sPATH(Ruby 3.1 or later);gem update rails-ai-contextbrings an older one up. A shim version manager (rbenv, asdf, or mise with its shims onPATH) picks that Ruby by the folder Claude Code starts in: that folder's.ruby-versionor.tool-versions, or the global one, so a session started above the app runs that folder's Ruby. A shell-hook one (rvm, chruby,mise activate) leaves the Ruby of the shell that started Claude Code, and a Claude Code started from the Dock or an IDE may see the system Ruby instead. An app that also has the gem in its Gemfile gets its bundled copy, as with any standalone install, a bundle kept under its own path such asvendor/bundletoo. A copy from git is the exception: the installed copy serves and the app's boot loads the git copy over it, so point the Gemfile at a release or apath:checkout. When the plugin cannot serve, its server still connects, with no tools, and tells the session why, naming the Ruby and the folder: no gem for that Ruby, an older one, a Ruby too old, a bundle Claude Code inherited frombundle execthat lacks the gem, no app or an app the gem cannot serve. The same line is the server's stderr, whichclaude --debugshows. From 5.38.0 the gem's own serve refuses the same way whatever stops it, and it keeps an app's bundled copy of any release behind it: a copy that stops before the handshake is answered by the same refusal, with what the copy printed, and one that stops later leaves an error naming that for each request. A start that fails before the plugin's script runs, such as an inherited bundle not installed for that Ruby (Bundler's trace, TROUBLESHOOTING.md), is listed as failed in/mcp, and Claude Code then skips the server in new sessions for about 15 minutes: reconnect it in/mcponce the cause is fixed. A session gets no rules where the server has no tools for them to name, but for a folder of several apps on Windows: there the rules come with a last line naming therails-ai-context --app-path <app> tool <name>commands to run instead. - Install the gem, not its setup, for Claude Code. Where the app's
.claude/settings.jsonturns the plugin on, the install generator andinitwrite no.mcp.jsonserver and say why, and so doesinitin a folder holding one app, where that folder's own.claude/settings.jsonturns it on; it still writes the app's own.mcp.jsonfor sessions started in the app, which do not read that folder's settings, and says so. In a folder of several apps whose own.claude/settings.jsonturns it on,initwrites no Claude Code server either, since the plugin serves each app there, and names the per-app servers an earlierinitleft in.mcp.json, which would list every tool twice;--pruneremoves the ones it wrote, and names any you wrote or added a key to, for you to remove. Where only your own settings turn it on, they still write one for the team, and their next step says to turn it off for yourself with/mcp. - The plugin or another server, not both. Claude Code starts the plugin's
server and one from
.mcp.jsonorclaude mcp add, an HTTP entry under the gem's name included, as two servers and lists every tool twice.doctorreads Claude Code the way a session does, by the folder it started in: that folder's settings and the local settings that reach it (its git repository's, a linked worktree's being its repository's, as "Where it runs" says), every.mcp.jsonfrom that folder up, the/mcptoggles and local servers Claude Code keeps for the repository, the MCP policy inallowedMcpServersanddeniedMcpServers(by name, command or url), and a deployedmanaged-mcp.json, whose servers are then the only ones Claude Code starts, each still subject to/mcpanddeniedMcpServers, and toallowedMcpServerswhere its entry expands a${VAR}, and the marketplace policy instrictKnownMarketplacesandblockedMarketplaces. It follows aCLAUDE_CONFIG_DIRset in your settings'envblock, as Claude Code does. It does not see settings an organization delivers from the Claude console, through MDM or the Windows registry, and it reads the managed settings files as if all of them were in force; where policy comes that way, its MCP verdicts can be wrong. It checks the shape ofenabledPluginsonly, while Claude Code ignores a whole settings file that breaks its schema elsewhere and says so when it starts: fix such a file first. It looks at the app, the folderdoctorruns in, the folders above the app that hold it alone, and the folders Claude Code keeps projects for. The plugin counts where it is enabled, installed for that project, not turned off in/mcpand not blocked by policy; then Claude Code's MCP check passes without a.mcp.json, and with no AI tools chosen it checks no other tool's config unless that config is broken. Where the plugin runs only for sessions started in another folder,doctornames that folder and what turns it on for this one. Where Claude Code never ran, as on CI, what the plugin needs is a warning, not a failure. Where it runs nowhere,doctornames why: not installed (with the install that leaves a committed file alone), a local marketplace folder that is gone, its server turned off in/mcp, the MCP or marketplace policy, a managed settings file Claude Code cannot read, or aCLAUDE_CONFIG_DIRthat is empty or not an absolute path, set in the environment or a settingsenvblock (doctornames which), which leaves each session reading its own folder's. A second server counts where such a session would start it, anddoctornames the command that removes it and the folder to run it in: a.mcp.jsonentry comes out where the committed settings turn the plugin on, and is turned off with/mcpwhere only your own settings do. - The rules load once. The hook skips them where Claude Code already loads
the generator's rules for that session: from the app's
CLAUDE.mdor.claude/rules/rails-mcp-tools.md, or from itsAGENTS.mdwhereCLAUDE.mdimports it or noCLAUDE.mdis on the way up from the folder the session started in, or from aCLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.mdon that way up that carries them, as an engine's above its test/dummy app does (your own~/.claude/CLAUDE.mddoes not count). It skips them too where.rails-ai-context.ymlor a configure block inconfig/application.rb, the environment's file or an initializer setsanti_hallucination_rulestofalseornil; a block's value wins over the file's, as when the app boots. It reads that Ruby without running it, so only a literal that ends its statement counts, and rule 3 leaves out therails_get_configsectionsskip_toolsturns off, in the YAML or a literal list, assigned or appended (=,<<chained or not,+=,|=,push,append,concat); a symbol appended in place, a Set or a value built at boot is not read, as the server skips none of those either. A session started above the app gets the rules from the hook, and once a file in the app is read, Claude Code also loads that app'sCLAUDE.md, so such a session can hold them twice. So can a session resumed after the app'sCLAUDE.mdgained the rules (frominit,contextor a pull), until/clearor a compaction. - Windows works the same. The server starts
rubywithout a shell, so it needs nocmdwrapper. -
One allowlist entry lasts. The server's command line names no plugin folder, so no update changes it, and under an
allowedMcpServerslist this entry admits it (doctornames it where it is missing). It admits any plugin that ships the same line, too. Where the list admits other stdio servers byserverName, adding this entry switches every stdio server to matching by command, so each of them needs aserverCommandentry as well;doctorsays so. Naming no script also keeps rbenv from picking the Ruby by the plugin's own folder.{"serverCommand":["ruby","-e","load File.join(ENV.fetch('CLAUDE_PLUGIN_ROOT'), 'scripts', 'serve.rb')"]} - Permission rules name the plugin's server. Its tools are
mcp__plugin_rails-ai-context_rails-ai-context__<tool>, so a rule for the.mcp.jsonserver (mcp__rails-ai-context) does not cover them;mcp__plugin_rails-ai-context_rails-ai-contextallows them all. - A slow app's boot. The plugin's server entry is the plugin's own, so set
RAILS_AI_CONTEXT_BOOT_TIMEOUTandMCP_TIMEOUTin Claude Code's settingsenv(user, project or local) or in the shell that starts Claude Code; see TROUBLESHOOTING.md. - Updates follow this repository. The plugin's version is the commit it was
installed from. Claude Code updates it only with auto-update on (under
/plugin, Marketplaces) orclaude plugin update rails-ai-context@rails-ai-context. The server is versioned by the gem:gem update rails-ai-context, then reconnect the server in/mcpor start a new session. Rungem cleanuponly after that: a running server loads its files as it needs them, so once its copy is gone, a call that needs a file it has not loaded yet answers with a request to reconnect it. - Removing it from one app is
claude plugin disable rails-ai-context@rails-ai-context --scope localrun there, which wins over your own and the committed settings for every session the local setting reaches ("Where it runs"). Taking an install out isclaude plugin uninstall rails-ai-context@rails-ai-context --scope <scope>, with the scope it went in at, run in the folder it was installed from: once for a user install, once per project for a project or local one. A marketplace added from a local folder or file runs the plugin with no install, so there only the disable turns it off. The gem'suninstallleaves Claude Code's settings alone and names those commands, one disable per repository whose sessions run the plugin, before it suggests removing the gem, which the plugin runs; where managed settings turn the plugin on, or a deployedmanaged-mcp.jsonruns the gem, it says to ask whoever manages them.
Split rules with paths: frontmatter
Claude Code loads .claude/rules/ files conditionally based on YAML frontmatter:
---
paths:
- "app/models/**/*.rb"
---
Schema, model and component rules use this to only load when relevant files are being edited.
Cursor
Auto-setup (recommended)
rails generate rails_ai_context:install --tools cursor --defaults # or run it bare and pick "Cursor"
rails-ai-context init --tools cursor --defaults # standalone
This creates:
.cursor/mcp.json- MCP config; restart Cursor and turn the server on under MCP in CustomizeAGENTS.md- Root context file. Cursor readsAGENTS.mdandCLAUDE.mdas it reads its own always-on rules (Cursor docs), on every surface.cursor/rules/rails-models.mdc- Model rules (Type 2: globapp/models/**/*.rb).cursor/rules/rails-controllers.mdc- Controller rules (Type 2: globapp/controllers/**/*.rb).cursor/rules/rails-project.mdc- Project overview (Type 1: alwaysApply), written only whengenerate_root_filesis off.cursor/rules/rails-mcp-tools.mdc- Tools guide (Type 1: alwaysApply), written only whengenerate_root_filesis off
.cursorrules is no longer written: Cursor calls it legacy, and reads the content from AGENTS.md. With root files on, a run takes out the block an earlier release wrote in .cursorrules and keeps your own lines; a file that held only the block is deleted.
Manual MCP config
Create .cursor/mcp.json:
{
"mcpServers": {
"rails-ai-context": {
"command": "bundle",
"args": ["exec", "rails-ai-context", "serve"]
}
}
}
Why the install's entry starts with ruby -e
The Cursor CLI (agent) starts a server with only HOME, LOGNAME, PATH, SHELL, TERM and USER. rvm and chruby also need GEM_PATH, so bundle or rails-ai-context cannot find their gems there and the server never starts. The install writes the command behind a one-line Ruby launcher: "command": "ruby", "args": ["-e", "<launcher>", "bundle", "exec", "rails-ai-context", "serve"]. When the client passed no GEM_PATH or GEM_HOME, the launcher sets GEM_PATH from the gem folders whose bin is on PATH (rvm and chruby put them there), keeps RubyGems' own folders, and starts the command. When the client passed either one, it starts the command unchanged. The plain entry above is enough where the client passes your shell's environment; with rvm or chruby in the CLI, let the install write the entry.
Tools guide rule
With generate_root_files off, the tools guide rule stands in for the root file, so it is always applied, like the project overview:
---
description: "Rails MCP tools guide - 35 tools for schema, models, routes, controllers, search and testing"
alwaysApply: true
---
GitHub Copilot
Auto-setup (recommended)
rails generate rails_ai_context:install --tools copilot --defaults # or run it bare and pick "GitHub Copilot"
rails-ai-context init --tools copilot --defaults # standalone
This creates:
.vscode/mcp.json- MCP config (VS Code format), started in a trusted workspace.github/mcp.json- MCP config for Copilot CLI, which reads it (and.mcp.json) and never.vscode/mcp.json. Copilot CLI loads it only in a folder you trust;copilot mcp listshows the server.github/copilot-instructions.md- Root instructions. WhereAGENTS.mdorCLAUDE.mdcarries the root content too, this is an identical copy: github.com chat, Visual Studio, JetBrains, Xcode and code review read no other file (GitHub docs), and Copilot CLI drops identical copies.github/instructions/rails-models.instructions.md- Model rules.github/instructions/rails-controllers.instructions.md- Controller rules.github/instructions/rails-context.instructions.md- Project overview, written only whengenerate_root_filesis off.github/instructions/rails-mcp-tools.instructions.md- Tools guide: the protocol, the workflows and the rules, as the root file carries them, written only whengenerate_root_filesis off
Manual MCP config
Create .vscode/mcp.json (note: servers key, not mcpServers):
{
"servers": {
"rails-ai-context": {
"command": "bundle",
"args": ["exec", "rails-ai-context", "serve"]
}
}
}
VS Code reads .vscode/mcp.json. Copilot CLI reads .github/mcp.json, which takes mcpServers and a tools list:
{
"mcpServers": {
"rails-ai-context": {
"command": "bundle",
"args": ["exec", "rails-ai-context", "serve"],
"tools": ["*"]
}
}
}
The install keeps a tools list you narrowed there. Its entry starts the command through the same ruby -e launcher as Cursor's (see Cursor). Copilot CLI 1.0.105 passes a server your whole environment, so there the launcher changes nothing, but GitHub's docs say only PATH is passed.
Copilot in JetBrains IDEs reads .github/mcp.json only under servers, and starts a server in the IDE's own folder, where the install's entries find no app. Give it the entry rails-ai-context mcp-entry prints, which starts from any folder: in Copilot Chat's agent mode, click the tools icon, then Add MCP Tools, and put the entry under servers in the mcp.json that opens.
Frontmatter for agent discovery
Copilot instruction files include applyTo:, name: and description: YAML frontmatter:
---
applyTo: "app/models/**/*.rb"
name: "Rails Models Reference"
description: "ActiveRecord models - associations, validations, scopes, enums"
---
OpenCode
Auto-setup (recommended)
rails generate rails_ai_context:install --tools opencode --defaults # or run it bare and pick "OpenCode"
rails-ai-context init --tools opencode --defaults # standalone
This creates:
opencode.json- MCP config, read when OpenCode startsAGENTS.md- Root context fileapp/models/AGENTS.md- Model-level rulesapp/controllers/AGENTS.md- Controller-level rules
Manual MCP config
Create opencode.json:
{
"mcp": {
"rails-ai-context": {
"type": "local",
"command": ["bundle", "exec", "rails-ai-context", "serve"]
}
}
}
Note: OpenCode uses an array for the command, not a string.
Codex CLI
Auto-setup (recommended)
rails generate rails_ai_context:install --tools codex --defaults # or run it bare and pick "Codex CLI"
rails-ai-context init --tools codex --defaults # standalone
This creates:
.codex/config.toml- MCP config (TOML format), committed like the other MCP configs. Codex reads a project's config only once you trust the project, which it asks the first time you start it there- Shares
AGENTS.mdand OpenCode rules files
Manual MCP config
Create .codex/config.toml:
[mcp_servers.rails-ai-context]
command = "bundle"
args = ["exec", "rails-ai-context", "serve"]
env_vars = ["GEM_HOME", "GEM_PATH", "GEM_ROOT", "RUBY_VERSION", "BUNDLE_PATH"]
startup_timeout_sec = 30.0
Why env_vars?
Codex starts an MCP server with a cleared environment that still keeps PATH, HOME, SHELL, USER, LANG, TMPDIR and a few more. env_vars names more variables to pass from the shell Codex was started in: rvm and chruby set these beside PATH, while rbenv, asdf and mise need only PATH. Nothing in the file is machine-specific, so a switch of Ruby needs no new install. Names you add to env_vars are merged into the one list.
startup_timeout_sec = 30.0 is there because Codex waited only 10 s for a server to start before 0.120, and the server boots the app first, for up to 20 s. A startup_timeout_sec or startup_timeout_ms you set is kept, and none is added beside it.
An earlier release saved this machine's PATH, GEM_HOME, GEM_PATH, GEM_ROOT, RUBY_VERSION and BUNDLE_PATH into an [mcp_servers.rails-ai-context.env] table. Running the install again (or a context run that rewrites MCP configs) replaces that table and drops them. Until then rails ai:doctor warns about the saved values, and fails the entry when the saved PATH no longer reaches its command. The install also takes out the .codex/config.toml line an earlier install added to .gitignore, so the file is committed like the other MCP configs.
The first step of a new session
Codex waits only about one second (mcp_optional_startup_grace_ms, default 1000) for a server still starting when it builds a step's tool list. So the first step of a new session, codex exec above all, can run without the rails tools while the app boots; later steps have them. To make Codex wait, add required = true to the [mcp_servers.rails-ai-context] table (Codex 0.100 or later). Then codex exec also exits with an error when the server cannot start. The install does not write it.
A folder of apps
When your AI tool opens a folder that holds several apps (work/shop, work/admin), run rails-ai-context init in that folder. Each AI tool reads its MCP config from the folder it opened, so the folder's configs get one server per app, and each app keeps its own .rails-ai-context.yml and context files:
| AI tool | Entry for work/shop |
|---|---|
Claude Code, Codex CLI, OpenCode, Cursor, Copilot CLI (.github/mcp.json) |
rails-ai-context serve --app-path shop, with RAILS_AI_CONTEXT_SERVER_NAME=shop-rails-ai-context |
GitHub Copilot in VS Code (.vscode/mcp.json) |
the same, with --app-path ${workspaceFolder}/shop |
A monorepo's root whose bin/rails boots an app below it is set up the same way, as a folder holding that one app: its .mcp.json names the app by --app-path, since a session started at the root reads that file. Claude Code, Codex, OpenCode, Copilot CLI and the Cursor CLI start a server in the folder they were launched in, so start them in work/; the Cursor editor starts it in the project's folder. The Claude Code plugin needs none of these entries: started in work/, its one server serves every app there, by the app each call names. Only VS Code expands ${workspaceFolder}, to the folder its config sits in; the Cursor CLI passes it on as literal text. A Cursor entry an earlier release wrote with ${workspaceFolder} is still read, and the next init in the folder rewrites it. An in-Gemfile app's entry runs bundle exec with BUNDLE_GEMFILE naming the Gemfile that app's bundle reads (its own, or a monorepo's shared one), spelled the same way. RAILS_AI_CONTEXT_SERVER_NAME makes each server announce its app first: VS Code names every tool after that name and keeps 13 characters of it. The full shape is in the CLI reference, and ADR-0005 records why.
HTTP Transport (alternative)
Instead of stdio, you can mount the MCP server inside your Rails app:
# config/routes.rb
mount RailsAiContext::Engine, at: "/mcp" if defined?(RailsAiContext::Engine)
The if keeps the routes file loading wherever the gem is not: in production, where Bundler skips the :development group, and after the gem is removed. An unguarded mount raises uninitialized constant RailsAiContext::Engine there, and the app does not boot.
The mounted engine answers the server-push channel (a long-lived SSE GET /mcp) with 405, which the MCP spec allows a server that sends no server-initiated messages: live reload, the one thing that sends them, runs only in the standalone rails-ai-context serve --transport http process. Clients carry on over POST, a connected client holds a server thread only while one of its requests runs, and rails server stops without waiting for clients to disconnect.
The engine runs each call on the thread Rails serves the request on and sends the answer whole, so calls keep being answered while the app reloads code after an edit. What a tool sends during a call reaches the client with the answer: a custom tool's progress or log notifications arrive together at the end, and a request a tool makes of the client mid-call (sampling, elicitation, roots) fails at once with a message saying why. stdio and the standalone HTTP server (rails-ai-context serve --transport http) deliver both as they are sent. For the same reason the engine answers subscriptions/listen, whose notification stream it cannot keep open, as a method it does not have.
With a migration pending in development, Rails answers every request to the app with its pending-migration page, and the mounted engine is one of those routes: it sits behind the app's whole middleware stack, ActiveRecord::Migration::CheckPending included, and cannot skip it without also skipping the cookies and session an authentication constraint around the mount needs. auto_mount answers ahead of that check, so its tools, which report the pending migration, keep working; so do stdio and the standalone server.
Then point your AI tool's MCP config to the HTTP endpoint instead of a command. Claude Code's .mcp.json needs the type (it skips a URL entry without one):
{
"mcpServers": {
"rails-ai-context": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
Cursor's .cursor/mcp.json takes {"url": "..."} under mcpServers, VS Code's .vscode/mcp.json takes {"type": "http", "url": "..."} under servers, and OpenCode's opencode.json takes {"type": "remote", "url": "..."} under mcp. rails-ai-context uninstall removes such an entry under the gem's name along with the rest.
Benefits: inherits Rails routing, authentication, and middleware stack. No separate process needed.
Running the install again keeps an entry like this one, under the gem's own name, in place of the command entry it would write, and says so.
Ruby in Docker
When Ruby and the gems live in a container and the AI tool runs on your machine, the server runs in the container and the MCP entry starts it through Docker. Install inside the container, then point the entry's command at it:
{
"mcpServers": {
"rails-ai-context": {
"command": "docker",
"args": ["compose", "exec", "-T", "web", "bundle", "exec", "rails-ai-context", "serve"]
}
}
}
With a plain container the args are ["exec", "-i", "CONTAINER", "bundle", "exec", "rails-ai-context", "serve"]. Keep -T (Compose) or -i (plain Docker) and never add -t: a terminal mangles the MCP messages. The container must be running before the AI tool starts. The install and every context run keep an entry whose command the gem did not write as it is, and say so; delete the entry and run the install again to go back to bundle exec. The Ruby runs in Docker prompt walks an AI tool through all of it. When the AI tool runs inside the container too (a devcontainer), nothing changes: use the usual install.
Other MCP clients
Claude Desktop, Windsurf, Zed, JetBrains IDEs and other clients get no config file from the install, and they start servers from their own folder with their own PATH. rails-ai-context mcp-entry prints an entry that works from anywhere: the real Ruby binary by its full path (past any version manager's shim, which would choose a Ruby by the client's folder), the gem's executable, --app-path naming the app, and the gem environment it needs:
rails-ai-context mcp-entry # standalone install
bundle exec rails-ai-context mcp-entry # in the Gemfile
Merge the printed rails-ai-context entry into the client's config under the key it uses for servers (mcpServers for most, servers for Copilot in JetBrains; Claude Desktop keeps it in claude_desktop_config.json). Run it again after the app moves or its Ruby changes. The Another MCP client prompt does this for you.
Verify MCP is connected
Each AI tool holds a project's MCP server back until you take one step in the tool. The install's closing summary names it for every tool you picked, under "Next step". Then check the server is up:
| AI tool | Step after the install | Check it is connected |
|---|---|---|
| Claude Code | Start a new claude session in the app's folder and approve rails-ai-context when it asks. To be asked again about a server you declined: claude mcp reset-project-choices |
/mcp in the session, or claude mcp list |
| Cursor | Restart Cursor, then turn rails-ai-context on under MCP in Customize if it is off. Cursor asks before each tool call unless you allow it |
Output panel (Cmd+Shift+U), "MCP Logs" |
| GitHub Copilot (VS Code) | Open the folder as a trusted workspace: a restricted one starts no workspace MCP server. VS Code starts the server when you send a Copilot Chat message | Command Palette, "MCP: List Servers", then the server's "Show Output" |
| GitHub Copilot CLI | Trust the folder when Copilot CLI asks: it loads .github/mcp.json only in a trusted folder |
copilot mcp list |
| OpenCode | Restart OpenCode in the app's folder | opencode mcp list |
| Codex CLI | Trust the project when Codex asks: Codex skips the .codex/config.toml of a project you have not trusted, and warns that it did. Then start a new codex session |
/mcp in the session, or codex mcp list |
Then ask the assistant something only the app knows, such as "What columns does the users table have?", and watch for a rails_get_schema call.
If the tools still don't appear
rails ai:doctor # in-Gemfile: checks every MCP config and whether its command can start
rails-ai-context doctor # standalone
bundle exec rails-ai-context serve # should start and wait on stdin (Ctrl+C to stop); drop bundle exec when standalone
Regenerating context files
After configuration changes:
rails ai:context # Regenerate for all configured tools
rails ai:context:claude # Regenerate for Claude only
rails ai:context:cursor # Regenerate for Cursor only
Or use watch mode for automatic regeneration:
rails ai:watch