rails-agent-kit
Ground truth about your Rails app, for coding agents
A read-only MCP server that gives Cursor, Claude Code, Codex and other MCP clients your app's real schema and routes, plus a Rails 8 skill that tells the agent to check them before it writes code.
Documentation · Install · Connect your agent · Tools · Changelog · Roadmap
Note
rails-agent-kit is early (v0.3.0), and the API may change before 1.0. Using it? Tell us how it went in Discussions or open an issue.
Look it up instead of guessing
Agents writing Rails code guess all the time. Is it user.full_name or user.name? Is the column nullable? Is
the helper post_comments_path or comments_path? Each wrong guess is broken code and another review round.
rails-agent-kit lets the agent ask your app.
-
Stack: Rails and Ruby versions, database, test framework, auth, jobs, frontend and deploy tools in one
small answer, read from
Gemfile.lockand config files, so the agent uses what the app already uses. -
Schema: tables, columns, indexes and foreign keys from
db/schema.rb, parsed statically. It never boots the app or connects to a database.db/structure.sqlgets a best-effort parse. - Schema overview and search: a compact overview by default, several tables in one call, and a name search across tables and columns, so large schemas don't flood the agent's context.
-
Routes: every route with its name, verb, path,
controller#actionand source line, from your app's ownbin/rails routes --expanded. Engines and route concerns resolve exactly as Rails sees them. -
The app's own Ruby: routes boot with the Ruby your app pins in
.ruby-version,.tool-versionsormise.toml, found through mise, rbenv, asdf or chruby. - Routes without booting: point it at a saved routes dump, or run the routes command in Docker.
-
One-command setup:
rails-agent-kit initconnects Cursor, Claude Code, VS Code and Codex, and installs the skill. -
Rails 8 conventions skill: an Agent Skill for Cursor and Claude Code, or a managed block in
AGENTS.md(Codex and others),.github/copilot-instructions.mdorGEMINI.md, installed withrails-agent-kit install-skills. - Read-only and local: a stdio server your client starts. It doesn't listen on a network port.
See what your agent sees
The agent calls the tools itself. These are real answers for the small blog app in
test/fixtures/blog_app, pretty-printed (the server sends compact JSON).
// rails_schema {} (the overview; trimmed)
{
"source": "db/schema.rb",
"table_count": 4,
"tables": [
{ "name": "comments", "columns": 6, "references": ["posts", "users"] },
{ "name": "posts", "columns": 10, "references": ["users"] },
{ "name": "posts_tags", "columns": 2, "primary_key": false },
{ "name": "users", "columns": 7 }
]
}// rails_schema { "search": "email" } (trimmed)
{ "match_count": 1, "matches": [{ "table": "users", "columns": [{ "name": "email", "type": "string", "null": false }] }] }// rails_schema { "table": "comments" } (trimmed)
{
"tables": [{
"name": "comments",
"columns": [
{ "name": "post_id", "type": "bigint", "null": false },
{ "name": "body", "type": "text", "null": false }
],
"indexes": [{ "name": "index_comments_on_post_id", "columns": ["post_id"], "unique": false }]
}],
"foreign_keys": [{ "from_table": "comments", "to_table": "users", "column": "user_id", "on_delete": "cascade" }]
}// rails_routes { "filter": "comments" } (trimmed)
{
"total": 7,
"count": 2,
"routes": [
{ "name": "post_comments", "verb": "POST", "path": "/posts/:post_id/comments(.:format)",
"controller_action": "comments#create", "source_location": "config/routes.rb:3" }
]
}Installation
gem install rails-agent-kitor, inside your Rails app:
bundle add rails-agent-kit --group developmentRequires Ruby 3.2+.
Connect your agent
One command
From your app's root:
bundle add rails-agent-kit --group development
bundle exec rails-agent-kit initinit writes the MCP config for Cursor (.cursor/mcp.json), Claude Code (.mcp.json) and VS Code
(.vscode/mcp.json), using project-relative paths so you can commit the files for your whole team. It adds
rails-agent-kit next to the servers you already have, picks bundle exec or the installed gem for you, installs the
Rails 8 skill for Cursor and Claude Code, adds it to AGENTS.md for Codex, and prints the snippet for Codex's
global ~/.codex/config.toml.
Running it again changes nothing. Preview with --dry-run, or pick clients with --agent cursor,claude.
By hand
Replace /path/to/your/rails/app with the absolute path to your app.
.cursor/mcp.json in your app (or ~/.cursor/mcp.json):
{
"mcpServers": {
"rails-agent-kit": {
"command": "rails-agent-kit",
"args": ["--root", "/path/to/your/rails/app"]
}
}
}claude mcp add rails-agent-kit -- rails-agent-kit --root /path/to/your/rails/appcodex mcp add rails-agent-kit -- rails-agent-kit --root /path/to/your/rails/appor in ~/.codex/config.toml:
[mcp_servers.rails-agent-kit]
command = "rails-agent-kit"
args = ["--root", "/path/to/your/rails/app"]Any client that launches stdio MCP servers works. Claude Desktop's claude_desktop_config.json takes the same
mcpServers block as Cursor above.
bundle add instead of gem install?Run it through the app's bundle:
{
"mcpServers": {
"rails-agent-kit": {
"command": "bundle",
"args": ["exec", "rails-agent-kit", "--root", "/path/to/your/rails/app"],
"env": { "BUNDLE_GEMFILE": "/path/to/your/rails/app/Gemfile" }
}
}
}claude mcp add rails-agent-kit -e BUNDLE_GEMFILE=/path/to/your/rails/app/Gemfile \
-- bundle exec rails-agent-kit --root /path/to/your/rails/appTo also add the Rails 8 conventions skill (optional), see Agent skill:
rails-agent-kit install-skills --root /path/to/your/rails/app # Cursor
rails-agent-kit install-skills --root /path/to/your/rails/app --agent claude # Claude Code
rails-agent-kit install-skills --root /path/to/your/rails/app --agent codex # AGENTS.md
rails-agent-kit install-skills --root /path/to/your/rails/app --agent copilot # GitHub Copilot
rails-agent-kit install-skills --root /path/to/your/rails/app --agent gemini # Gemini CLITools
All three tools are read-only and return JSON.
| Tool | Parameters | Returns | Boots the app? |
|---|---|---|---|
rails_project_info |
None | Rails, Ruby and load_defaults versions, api_only, database adapter and databases, test framework and data, auth, authorization, jobs/cache/cable backends, frontend, serializers, lint and deploy tools, mounted engines, notable gems and key paths. Unknown values are null
|
No. Reads Gemfile.lock and config files |
rails_schema |
All optional. table: one exact name, an array or a comma-separated list. search: case-insensitive part of a table or column name. detail: overview or full
|
With no arguments, a compact overview (each table's column count, non-default primary key and foreign key targets). With table, full columns (type, null, default, limit, …), indexes and foreign keys. With search, the matching tables and columns |
No. Parses db/schema.rb statically, with a best-effort fallback to db/structure.sql
|
rails_routes |
filter (optional, case-insensitive substring of name, path, verb or controller#action) |
Each route's name, verb, path, controller#action and source location |
Yes. Runs bin/rails routes --expanded. If that fails or times out, it explains why and returns the raw config/routes.rb
|
Responses are compact (single-line) JSON. Agents call rails_project_info first (about 1 KB), then usually
rails_schema with no arguments, so that
answer stays small even on large apps: a generated 300-table schema gives about 23 KB, where the full dump is
over 1 MB. Any rails_schema answer over 60 KB comes back as the overview plus a note on how to narrow the
request (truncated: true).
CLI reference
rails-agent-kit [--root PATH] [--routes-file FILE] # start the MCP server on stdio
rails-agent-kit init [--root PATH] [--agent LIST] [--dry-run] [--force] [--no-skills]
rails-agent-kit install-skills [--root PATH] [--agent AGENT] [--force] [SKILL...]
rails-agent-kit --version
| Option / env var | Purpose |
|---|---|
--root PATH |
Rails app root (default: the current directory) |
--routes-file FILE |
Use a saved bin/rails routes --expanded dump instead of booting the app |
RAILS_AGENT_KIT_ROUTES_TIMEOUT |
Seconds to wait for bin/rails routes (default 60) |
RAILS_AGENT_KIT_ROUTES_COMMAND |
Override the routes command, e.g. "docker compose exec -T web bin/rails routes --expanded". Runs in --root
|
If your app can't boot locally (it needs a DB, secrets or Docker), dump the routes once and point the server at the file:
bin/rails routes --expanded > tmp/routes.txt
rails-agent-kit --root . --routes-file tmp/routes.txtHow it works
-
Transport: a stdio MCP server built on the official
mcpRuby SDK. Your agent client starts it and talks JSON-RPC over stdin/stdout. Nothing listens on a network port. -
Schema: read from
db/schema.rbwith a static parser. It never loads your app or connects to a database, so it's fast and safe on any checkout. Apps that usedb/structure.sqlget a best-effort SQL parse. -
Routes: generated by your app itself (
bin/rails routes --expanded), so engines and route concerns resolve exactly as Rails sees them. It runs with the app's pinned Ruby and with Bundler's environment cleared, so the app uses its own Ruby and Gemfile. - Skill: a Markdown Agent Skill copied into your app. It tells the agent to call these tools before it writes model attributes, queries, URL helpers or migrations.
Agent skill: Rails 8 conventions
skills/rails-8-conventions/SKILL.md makes the agent check rails_project_info,
rails_schema and rails_routes before it edits code. It then follows the Rails 8 defaults: params.expect, the
built-in authentication generator, rate_limit, Solid Queue/Cache/Cable, Hotwire with importmap/Propshaft,
reversible migrations, and tests in the framework the app already uses. It also covers a paired Next.js
frontend.
There's one source for every agent. install-skills installs it where each agent looks:
--agent |
Writes | Read by |
|---|---|---|
cursor (default) |
.cursor/skills/<name>/SKILL.md |
Cursor |
claude |
.claude/skills/<name>/SKILL.md |
Claude Code (and Cursor, Copilot) |
codex |
A managed block in AGENTS.md
|
Codex, Cursor, GitHub Copilot, Windsurf, Zed and other AGENTS.md readers |
copilot |
A managed block in .github/copilot-instructions.md
|
GitHub Copilot |
gemini |
A managed block in GEMINI.md
|
Gemini CLI |
Running it again is safe. It never overwrites a skill file you've edited unless you pass --force. In
AGENTS.md, copilot-instructions.md and GEMINI.md it only touches the text between
<!-- rails-agent-kit:start --> and <!-- rails-agent-kit:end -->, appending the block if it isn't there yet,
so the rest of your file stays yours.
Compatibility
| Versions | Status | |
|---|---|---|
| Ruby | 3.2, 3.3, 3.4, 4.0 | Tested in CI (ruby-head runs too, allowed to fail) |
Rails (db/schema.rb format) |
8.0 | Covered by test fixtures |
| Rails | 7.2, 8.1 | Expected to work, but not yet covered by CI (planned) |
| MCP clients | Cursor, Claude Code, Codex, Claude Desktop, or any stdio MCP client | Configuration shown above |
The bundled skill targets Rails 8 conventions. On Rails 7.x, the tools work the same, but some skill advice
(e.g. params.expect and Solid Queue defaults) won't apply.
Documentation
The full guide lives at afurm.github.io/rails-agent-kit: getting started, a page per tool with example output, the CLI reference, the agent skill and compatibility.
Connect your agent · Tools · CLI reference · Changelog · Roadmap · Releasing · Security
Community
- Questions and ideas: GitHub Discussions
- Bugs: open an issue with your Ruby, Rails and MCP client versions
- Vulnerabilities: report them privately, as described in SECURITY.md
Everyone taking part follows the Code of Conduct.
Contributing
Pull requests are welcome. Read CONTRIBUTING.md, then:
gh repo fork afurm/rails-agent-kit --clone && cd rails-agent-kit
bundle install
bundle exec rake testLicense
MIT © Andrii Furmanets