Adding MCP to a Rails app

A server provides tools, prompts, and resources (I'll focus only on tools). While a client connects to one, or multiple, servers and exposes their tools to an LLM. The client then makes API requests to the Servers to use tools when the LLM tells it to.

In essence - the Client uses the LLM as a brain to plan out how to solve a problem and the Servers as tools to implement the solution.

bundle add fast-mcp
bin/rails generate fast_mcp:install

mkdir app/mcp
mv app/tools app/mcp/tools
mv app/resources app/mcp/resources

# config/initializers/zeitwerk.rb

module MCP; end

Rails.autoloaders.main.tap do |autoloader|
  Dir.glob(Rails.root.join("app/mcp/*")).each do |file|
    next unless File.directory?(file)

    autoloader.push_dir(file, namespace: MCP)
  end
end

bin/rails s

curl -v http://localhost:3000/mcp/sse
* Host localhost:3000 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:3000...
* Connected to localhost (::1) port 3000
* using HTTP/1.x
> GET /mcp/sse HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/8.13.0
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 200 OK
< Content-Type: text/event-stream
< Cache-Control: no-cache, no-store, must-revalidate
< Connection: keep-alive
< X-Accel-Buffering: no
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Methods: GET, OPTIONS
< Access-Control-Allow-Headers: Content-Type
< Access-Control-Max-Age: 86400
< Keep-Alive: timeout=600
< Pragma: no-cache
< Expires: 0
* no chunk, no close, no size. Assume close to signal end
<
: SSE connection established

event: endpoint
data: /mcp/messages?

retry: 100

: keep-alive 1

: keep-alive 2

: keep-alive 3

: keep-alive 4

: keep-alive 5

event: message
data: {"jsonrpc":"2.0","method":"ping","id":715239

paru -Sy zed-preview-bin
zeditor .

npx [email protected] http://localhost:3000/mcp/sse --allow-http --skip-browser-auth

Can you greet a User with ID 636166899? 

To my surprise it didn't respond with a greeting but started digging through the codebase

After some digging around I soon discovered that, while the server was running, it wasn't advertising any tools.

The problem was that the initializer for Fast MCP uses the descendants method to load all tools that inherit from ApplicationTool.

server.register_tools(*MCP::ApplicationTool.descendants)
server.register_resources(*MCP::ApplicationResource.descendants

Foo.descendants
# => []

class Bar < Foo
end

Foo.descendants
# => [Bar]

# config/environment/development.rb

Rails.application.configure do
  # Eager load all classes if the EAGER_LOAD ENV is set
  config.eager_load = !!ENV['EAGER_LOAD']
  # ...
end

EAGER_LOAD=1 bin/rails s

After some more digging I concluded that, to test my MCP server I'd have to create a new Profile

.

.

.

And then configure that Profile's tools to include only my MCP server's tools.

.

With that configured I tried the prompt again and this time it worked!

Building a tool

module MCP
  class SearchBuildingsTool < ApplicationTool
    tool_name "search_buildings"
    description "Searches for buildings"

    arguments do
      optional(:building_ids).array(:integer).description("IDs of the Buildings to look up")
      optional(:query).maybe(:string).description("The search query")
    end

    def call(building_ids: nil, query: nil,)
      buildings = Building.all

      if building_ids.present?
        buildings = buildings.where(id: building_ids)
      end

      if query.present?
        buildings = buildings.where("name LIKE :query OR handle LIKE :query", query: "%#{query}%")
      end

      buildings
	    .limit(50)
	    .order(name: :desc)
	    .to_json(only: [:id, :name, :handle, :address])
    end
  end
end

Then I wanted to implement Access Tool search. But to search Access Tools you need a building ID. I wasn't sure if the LLM could combine multiple tools by first searching for the building, getting its ID and then searching for the access logs with that ID. And I couldn't find a definitive answer online so I hoped for the best and implemented the following

module MCP
  class SearchAccessLogsTool < ApplicationTool
    tool_name "search_access_logs"
    description "Searches through Access Logs and returns the fist 25 results"

    arguments do
      required(:building_id).filled(:integer).description("ID of the Building that we are searching in")
      optional(:query).maybe(:string).description("The search query")
    end

    def call(building_id: nil, query: nil)
      building = begin
        Building.find(building_id)
      rescue ActiveRecord::RecordNotFound
        return "Building not found"
      end

	  building
	    .access_logs
	    .search({ query: query })
	    .order(logged_at: :desc)
	    .limit(25)
	    .to_json(only: [
	      :id, 
	      :logged_at, 
	      :grantor, 
	      :description,
	      :access_point_id,
	      :status
	    ])
    end
  end
end

To my surprise this worked! It reused the ID it found in the previous response to search for the access logs.

I was curious if it could actually combine tools so I started a new chat and asked the same question.

The response blew my mind. It could combine tools! To me, this was both incredible and scary. Kind of like seeing primates use tools or develop their own economy.

module MCP
  class SearchAccessLogsTool < ApplicationTool
    tool_name "search_access_logs"
    description <<~MD
      Searches for Access Logs in a given building and returns
      a JSON string containing an array of up to 25 objects.
      The list is sorted in descending order by the time 
      the access log was logged.
      Inputs:
      - building_id [Integer] (the ID of the building in which to search for access logs)
      - query [String, null] (a plain string that can contain any part ot the name of the grantor, the id of the access log, the description, the id of the associated access point)
      - logged_after [String, null] (An ISO8601 timestamp of the earliest time a log was recorded)
      - logged_before [String, null] (An ISO8601 timestamp of the latest time a log was recorded)
      - statuses [Array[String], null] (A comma-separated list of statuses)
      Output:
      - id [Integer] (The ID of the access log record)
      - logged_at [String] (ISO8601 timestamp of the time the log was recorded)
      - grantor [String, null] (Name of the person that granted this access, a null value means that the system granted the access)
      - description [String] (A description of what happened)
      - access_point_id [Integer] (ID of the access point that was accessed)
      - status [String] (The access point's state after this access)

      Statuses:
      - open - means that the access point was unlocked and that someone opened it
      - closed - means that the access point was unlocked, opened and then closed
      - left_ajar - means that the access point was unlocked, and then left open for more than 1min
      - denied - the access point never unlocked
      
      If the building couldn't be found you'll get a message back stating that.
    MD

    arguments do
      required(:building_id)
        .filled(:integer)
        .description("ID of the Building that we are searching in")
      optional(:query)
        .maybe(:string)
        .description("The search query which can contain any part of the grantors name, id of the record, id of the access point, or part of the description; any other input will be ignored")
      optional(:status)
	    .maybe(:string)
	    .description("Comma-separated list of statuses - valid statuses are open, closed, left_ajar, denied; any other statuses will be ignored")
    end

    def call(**args)
      # ...
    end
  end
end

• Describe the output (it's as important as describing the input)
• Describe error states
• List all possible enum values and describe what each value means
• Explicitly state what format you expect for an input (what kind of timestamp do you expect, can it be nullable, etc.)
• Explicitly state what's not allowed (e.g. additional enum values besides the ones listed)

value.presence&.to_s&.strip&.singularize&.underscore