AI Tool Setup

Per-editor setup for Claude Code, Cursor, Copilot, OpenCode, and Codex CLI.

Quickstart · Configuration · Standalone · Troubleshooting


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?

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

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:

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.

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

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:

.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

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:

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

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:

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

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:

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

← Configuration · Architecture →

Back to Home