MCP Server

Query BuiltOnRails stack intelligence directly from Claude Code, Cursor, or any MCP-compatible AI assistant. No API key needed — all data is public.

Connect

# Claude Code
claude mcp add builtonrails --transport sse https://builtonrails.com/mcp/sse

# Local development
claude mcp add builtonrails-dev --transport sse http://localhost:3037/mcp/sse

# Product owners: registration with a write-scope API key (enables my_product)
claude mcp add builtonrails-owner --transport sse https://builtonrails.com/mcp/sse \
  --header "Authorization: Bearer YOUR_API_KEY"

# Admins: registration with an admin API key (enables the admin_* tools)
claude mcp add builtonrails-admin --transport sse https://builtonrails.com/mcp/sse \
  --header "Authorization: Bearer YOUR_ADMIN_API_KEY"

A machine-readable manifest is served at /.well-known/mcp.json.

Then just ask your AI natural questions about Rails stacks. It will call the right tools automatically.

Transport

Endpoint	Transport	Description
/mcp/sse	SSE	Server-Sent Events (recommended for Claude Code)
/mcp/messages	HTTP	Standard HTTP transport

No authentication required for the 12 public tools. my_product requires a write-scope API key, and the three admin_* tools an admin key — both sent as a Bearer token (see Tools — Owners and Tools — Admin below).

---

Tools — Stack Intelligence

search_stacks

Search for technology stacks (gems, frameworks, services) by name or category. Returns real adoption data from production Rails apps.

Parameters:

Name	Type	Required	Description
query	string	yes	Search term (e.g. "sidekiq", "auth", "postgres")
category	string	no	Filter by category: Framework, Database, Frontend, Background, Search, Auth, Payments, DevOps, Testing, Analytics, LLM, AI/ML, Observability, Security, Email

Example response:

{
  "query": "auth",
  "results_count": 3,
  "stacks": [
    {
      "name": "Devise",
      "category": "Auth",
      "products_count": 28,
      "github_stars": 23900,
      "popular": true
    }
  ]
}

---

compare_stacks

Head-to-head comparison of two stacks. Uses the same scoring algorithm as Stack Showdown — weighted by product adoption, collections, GitHub stars, and community signals.

Parameters:

Name	Type	Required	Description
stack1	string	yes	First stack name (e.g. "Sidekiq")
stack2	string	yes	Second stack name (e.g. "Solid Queue")

Example response:

{
  "stack1": {
    "name": "Sidekiq",
    "products_count": 32,
    "github_stars": 13200,
    "score": 385
  },
  "stack2": {
    "name": "Solid Queue",
    "products_count": 47,
    "github_stars": 1900,
    "score": 521
  },
  "winner": {
    "winner": "Solid Queue",
    "score_difference": 136
  }
}

---

get_stack_recommendations

Get recommendations based on what real Rails apps use together. Given your current stacks and a target category, it finds all products using your stacks and counts which other stacks in that category they use — ranked by frequency.

Parameters:

Name	Type	Required	Description
current_stacks	array of strings	yes	Your current stacks (e.g. ["PostgreSQL", "Hotwire"])
category	string	yes	Category to get recommendations for (e.g. "Background", "Auth")

Example response:

{
  "current_stacks": ["PostgreSQL", "Hotwire"],
  "category": "Background",
  "products_analyzed": 34,
  "recommendations": [
    {
      "name": "Solid Queue",
      "co_occurrence_count": 28,
      "confidence": "82%"
    }
  ]
}

---

get_stack_trends

Historical adoption trends for a technology stack. Shows how many Rails apps use the stack over time, plus growth percentage.

Parameters:

Name	Type	Required	Description
stack_name	string	yes	Stack name (e.g. "Solid Queue")
days	integer	no	Days of history (default: 90, max: 365)

Example response:

{
  "stack": {
    "name": "Solid Queue",
    "category": "Background",
    "current_products_count": 47
  },
  "trend": {
    "period_growth_percent": 52,
    "recent_30_day_growth_percent": 22,
    "snapshots": [
      { "date": "2025-11-15", "products_count": 31 },
      { "date": "2026-01-15", "products_count": 47 }
    ]
  }
}

---

get_categories

Get all available stack categories with descriptions and stack counts. Useful for understanding what types of technologies are tracked.

Parameters: None

Example response:

{
  "total_categories": 15,
  "categories": [
    { "name": "Framework", "description": "Web frameworks", "stacks_count": 12 },
    { "name": "Database", "description": "Databases & storage", "stacks_count": 10 },
    { "name": "Auth", "description": "Authentication & authorization", "stacks_count": 8 }
  ]
}

---

Tools — Products

search_products

Search and browse Rails applications in the directory. Returns approved products with name, URL, type, votes, and stacks.

Parameters:

Name	Type	Required	Description
query	string	no	Search term to match product name (e.g. "shopify", "hey")
type	string	no	Filter by product type (e.g. "SaaS", "Gem", "DevTool")
sort	string	no	Sort order: "votes" (most upvoted) or "newest" (default)
limit	integer	no	Max results (default: 10, max: 25)

Example response:

{
  "query": "shop",
  "results_count": 2,
  "products": [
    {
      "name": "Shopify",
      "slug": "shopify",
      "url": "https://shopify.com",
      "product_type": "SaaS",
      "votes_count": 127,
      "stacks": [
        { "name": "PostgreSQL", "category": "Database" },
        { "name": "Sidekiq", "category": "Background" }
      ],
      "builtonrails_url": "https://builtonrails.com/products/shopify"
    }
  ]
}

---

get_product

Get detailed information about a specific Rails application including description, tags, member, and full stack list.

Parameters:

Name	Type	Required	Description
slug	string	yes	Product slug (e.g. "shopify", "hey", "github")

Example response:

{
  "name": "Shopify",
  "slug": "shopify",
  "url": "https://shopify.com",
  "description": "Commerce platform built on Rails",
  "product_type": "SaaS",
  "tags": ["ecommerce", "saas"],
  "votes_count": 127,
  "verified": true,
  "member": { "username": "tobi", "display_name": "Tobi Lutke" },
  "stacks": [
    { "name": "PostgreSQL", "category": "Database", "github_stars": null },
    { "name": "Sidekiq", "category": "Background", "github_stars": 13200 }
  ],
  "builtonrails_url": "https://builtonrails.com/products/shopify"
}

---

get_products_using_stacks

Find real Rails applications that use specific technology stacks. Returns approved products using all specified stacks.

Parameters:

Name	Type	Required	Description
stacks	array of strings	yes	Stack names to filter by (e.g. ["PostgreSQL", "Sidekiq"])
limit	integer	no	Max results (default: 10, max: 25)

Example response:

{
  "searched_stacks": ["PostgreSQL", "Sidekiq"],
  "total_matches": 18,
  "showing": 3,
  "products": [
    {
      "name": "Shopify",
      "slug": "shopify",
      "votes_count": 127,
      "stacks": [
        { "name": "PostgreSQL", "category": "Database" },
        { "name": "Sidekiq", "category": "Background" }
      ],
      "builtonrails_url": "https://builtonrails.com/products/shopify"
    }
  ]
}

---

Tools — Detection

detect_stacks

Detect technology stacks from a Gemfile, package.json, or importmap.rb content. Paste your dependency file and get matched stacks with adoption data. The killer feature for coding agents — understand your project's stack landscape instantly.

Parameters:

Name	Type	Required	Description
gemfile	string	no	Raw Gemfile content
package_json	string	no	Raw package.json content
importmap	string	no	Raw config/importmap.rb content

At least one parameter is required.

Example response:

{
  "matched_count": 8,
  "stacks": [
    { "name": "PostgreSQL", "category": "Database", "products_count": 89, "popular": true },
    { "name": "Sidekiq", "category": "Background", "products_count": 32, "popular": true },
    { "name": "Devise", "category": "Auth", "products_count": 28, "popular": true }
  ]
}

---

get_collection

Retrieve a curated stack collection by slug. Collections are hand-picked sets of stacks with notes and optional LLM prompts — ready-made context for AI coding sessions.

Parameters:

Name	Type	Required	Description
slug	string	yes	Collection slug (e.g. "modern-rails-2024")

Example response:

{
  "name": "Modern Rails 2024",
  "slug": "modern-rails-2024",
  "description": "The essential stack for new Rails projects",
  "llm_prompt": "Build a Rails 8 app with these technologies...",
  "stacks": [
    { "name": "Ruby on Rails", "category": "Framework", "note": "Use Rails 8 with Solid Queue" },
    { "name": "PostgreSQL", "category": "Database", "note": null }
  ],
  "builtonrails_url": "https://builtonrails.com/collections/modern-rails-2024"
}

---

Tools — Submissions

submit_product

Submit a new Rails application to the directory. Created with "pending" status — goes through admin approval. Pasting your dependency files (gemfile / package_json / importmap) is the recommended path: the real stack is detected and attached automatically, and verified stacks are the whole point of the directory.

Parameters:

Name	Type	Required	Description
name	string	yes	Product name (e.g. "Shopify")
url	string	yes	Product website URL
description	string	yes	Short description
product_type	string	no	Type: SaaS, DevTool, Gem, Marketplace, E-commerce, Fintech, Template, and more
stacks	array of strings	no	Stack names to associate (e.g. ["PostgreSQL", "Sidekiq"])
gemfile	string	no	Raw Gemfile content — stacks auto-detected and attached
package_json	string	no	Raw package.json content — stacks auto-detected and attached
importmap	string	no	Raw config/importmap.rb content — stacks auto-detected and attached

Example response:

{
  "status": "submitted",
  "message": "Product submitted for admin approval",
  "product": {
    "name": "My App",
    "slug": "my-app",
    "status": "pending",
    "stacks_attached": 3
  }
}

---

Tools — News

get_news

Read curated Rails ecosystem news — the same pipeline behind builtonrails.com/daily.

Parameters:

Name	Type	Required	Description
category	string	no	article, release, podcast, video, news
date	string	no	Specific day, YYYY-MM-DD
query	string	no	Search term matched against title and summary
limit	integer	no	Max results (default 15, max 50)

---

Tools — Owners (write-scope key required)

my_product

Manage your own products conversationally. Requires a write-scope API key sent as a Bearer token; you can only touch products you submitted or founded (via the product team).

Actions:

Action	Description
list	Your products with votes, views, and update counts
update	Edit a product by slug: description, url, product_type, tags, github_repo_path (linking a GitHub repo auto-syncs its stacks)
post_update	Publish a product update: title + update_type (release, feature, announcement, blog, video, milestone …), optional content, url, version
updates	A product's 20 most recent updates

Status and featuring stay admin-only — update refuses them, and unowned slugs return an error.

---

Example Prompts

Once connected, ask your AI natural questions. It will call the right tools automatically:

• "What background job library should I use with PostgreSQL and Hotwire?" — calls get_stack_recommendations
• "Compare Devise vs Rodauth for authentication" — calls compare_stacks
• "Show me production Rails apps using Solid Queue and Turbo" — calls get_products_using_stacks
• "Is Solid Queue adoption growing?" — calls get_stack_trends
• "What testing libraries are most popular for Rails?" — calls search_stacks
• "Get the modern-rails-2024 collection" — calls get_collection
• "What stacks does Shopify use?" — calls get_product
• "Find the top Rails SaaS apps" — calls search_products
• "Scan my Gemfile and tell me what stacks I'm using" — calls detect_stacks
• "What categories of stacks do you track?" — calls get_categories
• "What's new in Rails this week?" — calls get_news
• "Submit my Rails app to the directory" — calls submit_product
• "Post a release note for my app: v2.1 shipped" — calls my_product (write key)

---

Tools — Admin (Bearer token required)

admin_moderation

Moderate the directory over MCP. Requires an admin API key sent as a Bearer token — the same keys as the internal API. Without a valid admin token the tool refuses.

Actions: pending (review queue), approve / reject (by product slug), feature / unfeature, stats.

Configure your MCP client to send the header:

Authorization: Bearer <your-admin-api-key>

admin_news

Batch-review the curated news queue (the pipeline behind /daily and the newsletter).

Actions: queue (list pending items; filter by feed name or query), select / reject (batch by ids, max 100 per call), stats (queue counts by status and feed).

admin_sponsors

Manage site sponsors end to end.

Actions: list (with impressions/clicks/CTR), create / update (name, url, position, tagline, cta_text, starts_at, ends_at), activate / deactivate, inquiries + inquiry_status (pending → contacted → converted/declined), orders (self-serve Stripe orders).