ruby-sdk/examples/rails

Rails Example MCP Server

A minimal Rails application that serves an MCP server over the Streamable HTTP transport, following the "Rails (mount)" pattern from the top-level README.

The application provides:

• add_tool tool (app/tools/add_tool.rb) - adds two numbers, demonstrates input_schema
• greeting_tool tool (app/tools/greeting_tool.rb) - greets a name, demonstrates annotations and server_context
• example://rails/readme resource - a text resource served via resources_read_handler

The MCP server and transport are built once at boot in config/routes.rb, where the transport is mounted at /mcp.

Requirements

• Ruby >= 3.2 (required by Rails 8; the mcp gem itself supports older Rubies)
• curl >= 7.82 (for the --json flag used below)

Running

$ cd examples/rails
$ bundle install
$ bundle exec puma --port 9292

The MCP endpoint is now available at http://localhost:9292/mcp.

Testing with cURL

POST requests must include an Accept header that allows both application/json and text/event-stream, per the MCP Streamable HTTP transport spec. Responses arrive as SSE data: lines.

1. Initialize a session and capture the session ID:

SESSION_ID=$(curl -s -D - -o /dev/null http://localhost:9292/mcp \
  -H "Accept: application/json, text/event-stream" \
  --json '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' \
  | grep -i "^mcp-session-id:" | cut -d' ' -f2 | tr -d '\r')

2. Complete the handshake (expect 202 Accepted):

curl -i http://localhost:9292/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  --json '{"jsonrpc":"2.0","method":"notifications/initialized"}'

3. List and call tools:

curl http://localhost:9292/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  --json '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

curl http://localhost:9292/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  --json '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add_tool","arguments":{"a":5,"b":3}}}'

curl http://localhost:9292/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  --json '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"greeting_tool","arguments":{"name":"Rails"}}}'

4. List and read the resource:

curl http://localhost:9292/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  --json '{"jsonrpc":"2.0","id":5,"method":"resources/list"}'

curl http://localhost:9292/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  --json '{"jsonrpc":"2.0","id":6,"method":"resources/read","params":{"uri":"example://rails/readme"}}'

5. Optionally, open the standalone SSE stream for server-to-client messages (in another terminal):

curl -N http://localhost:9292/mcp \
  -H "Accept: text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID"

6. End the session:

curl -i -X DELETE http://localhost:9292/mcp -H "Mcp-Session-Id: $SESSION_ID"

Testing with MCP Inspector

Start MCP Inspector with npx @modelcontextprotocol/inspector, set Transport Type to "Streamable HTTP", and connect to http://localhost:9292/mcp.

Notes

• StreamableHTTPTransport keeps session and SSE state in memory, so it must run in a single process. Puma runs in single mode (workers 0) by default; do not enable clustered mode for this app. When running multiple instances behind a load balancer, use sticky sessions keyed on the Mcp-Session-Id header, or pass stateless: true to the transport.
• The server is built once at boot in config/routes.rb, so code reloading is disabled (config.enable_reloading = false in config/application.rb). Restart the server after changing tool or resource code. Note that tool classes cannot be referenced from config/initializers because Zeitwerk has not set up autoloading at that point; routes load late enough that they can.
• For a per-request server with request-specific tools or context, see the "Rails (controller)" section in the top-level README, which uses stateless: true and transport.handle_request(request) inside a controller action.