MCP Ruby SDK

MCP Ruby SDK

The official Ruby SDK for Model Context Protocol servers and clients.

Detailed guides are available at https://ruby.sdk.modelcontextprotocol.io.

Features

• Build MCP servers that expose tools, prompts, and resources to any MCP host, with OAuth 2.1 resource-server protection
• Build MCP clients that connect to any MCP server, with automatic lifecycle negotiation and OAuth 2.1 authorization
• Speak every standard transport: stdio and Streamable HTTP (including SSE), with a Rails integration
• Cover the full protocol surface: server-to-client requests, multi round-trip requests, notifications, progress, logging, cancellation, completions, and pagination

Installation

Add this line to your application's Gemfile:

gem "mcp"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install mcp

You may need to add additional dependencies depending on which features you wish to access.

Quick Start

The following minimal programs show both sides of the protocol: a server that exposes a single tool, and a client that spawns such a server and drives it over stdio.

MCP Server

A minimal server defines a tool and serves it over the stdio transport:

require "mcp"

# Create a simple tool
class ExampleTool < MCP::Tool
  description "A simple example tool that echoes back its arguments"
  input_schema(
    properties: {
      message: { type: "string" },
    },
    required: ["message"]
  )

  class << self
    def call(message:, server_context:)
      MCP::Tool::Response.new([{
        type: "text",
        text: "Hello from example tool! Message: #{message}",
      }])
    end
  end
end

# Set up the server
server = MCP::Server.new(
  name: "example_server",
  tools: [ExampleTool],
)

# Create and start the transport
transport = MCP::Server::Transports::StdioTransport.new(server)
transport.open

Save the script as server.rb, run it, and send JSON-RPC requests via stdin:

$ ruby server.rb
{"jsonrpc":"2.0","id":"1","method":"ping"}
{"jsonrpc":"2.0","id":"2","method":"tools/list"}
{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"example_tool","arguments":{"message":"Hello"}}}

The same server can also run over Streamable HTTP, including mounted inside a Rails application; see Server Transports.

MCP Client

A minimal client spawns a stdio server as a subprocess, connects, and lists and calls its tools:

require "mcp"

stdio_transport = MCP::Client::Stdio.new(
  command: "bundle",
  args: ["exec", "ruby", "path/to/server.rb"],
  env: { "API_KEY" => "my_secret_key" },
  read_timeout: 30
)
client = MCP::Client.new(transport: stdio_transport)

# Negotiate the protocol lifecycle before sending any requests.
client.connect

# List available tools.
tools = client.tools
tools.each do |tool|
  puts "Tool: #{tool.name} - #{tool.description}"
end

# Call a specific tool.
response = client.call_tool(
  tool: tools.first,
  arguments: { message: "Hello, world!" }
)

# Close the transport when done.
stdio_transport.close

The same client can connect to Streamable HTTP servers with MCP::Client::HTTP; see Client Transports.

Examples

Runnable examples are available in examples, including a complete Rails application in examples/rails.

Documentation

• SDK guides
• SDK API documentation
• Model Context Protocol documentation

License

This project is licensed under the Apache License 2.0 for new contributions, with existing code under MIT. See the LICENSE file for details.