ruby-sdk

# MCP Ruby SDK [](https://rubygems.org/gems/mcp) [](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/LICENSE.txt) [](https://github.com/modelcontextprotocol/ruby-sdk/actions/workflows/ci.yml) The official Ruby SDK for Model Context Protocol servers and clients. ## Installation Add this line to your application's Gemfile: ```ruby gem 'mcp' ``` And then execute: ```console $ bundle install ``` Or install it yourself as: ```console $ gem install mcp ``` You may need to add additional dependencies depending on which features you wish to access. ## Building an MCP Server The `MCP::Server` class is the core component that handles JSON-RPC requests and responses. It implements the Model Context Protocol specification, handling model context requests and responses. ### Key Features - Implements JSON-RPC 2.0 message handling - Supports protocol initialization and capability negotiation - Manages tool registration and invocation - Supports prompt registration and execution - Supports resource registration and retrieval - Supports stdio & Streamable HTTP (including SSE) transports - Supports notifications for list changes (tools, prompts, resources) ### Supported Methods - `initialize` - Initializes the protocol and returns server capabilities - `ping` - Simple health check - `tools/list` - Lists all registered tools and their schemas - `tools/call` - Invokes a specific tool with provided arguments - `prompts/list` - Lists all registered prompts and their schemas - `prompts/get` - Retrieves a specific prompt by name - `resources/list` - Lists all registered resources and their schemas - `resources/read` - Retrieves a specific resource by name - `resources/templates/list` - Lists all registered resource templates and their schemas ### Custom Methods The server allows you to define custom JSON-RPC methods beyond the standard MCP protocol methods using the `define_custom_method` method: ```ruby server = MCP::Server.new(name: "my_server") # Define a custom method that returns a result server.define_custom_method(method_name: "add") do |params| params[:a] + params[:b] end # Define a custom notification method (returns nil) server.define_custom_method(method_name: "notify") do |params| # Process notification nil end ``` **Key Features:** - Accepts any method name as a string - Block receives the request parameters as a hash - Can handle both regular methods (with responses) and notifications - Prevents overriding existing MCP protocol methods - Supports instrumentation callbacks for monitoring **Usage Example:** ```ruby # Client request { "jsonrpc": "2.0", "id": 1, "method": "add", "params": { "a": 5, "b": 3 } } # Server response { "jsonrpc": "2.0", "id": 1, "result": 8 } ``` **Error Handling:** - Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method - Supports the same exception reporting and instrumentation as standard methods ### Notifications The server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling. #### Notification Methods The server provides three notification methods: - `notify_tools_list_changed` - Send a notification when the tools list changes - `notify_prompts_list_changed` - Send a notification when the prompts list changes - `notify_resources_list_changed` - Send a notification when the resources list changes #### Notification Format Notifications follow the JSON-RPC 2.0 specification and use these method names: - `notifications/tools/list_changed` - `notifications/prompts/list_changed` - `notifications/resources/list_changed` #### Transport Support - **stdio**: Notifications are sent as JSON-RPC 2.0 messages to stdout - **Streamable HTTP**: Notifications are sent as JSON-RPC 2.0 messages over HTTP with streaming (chunked transfer or SSE) #### Usage Example ```ruby server = MCP::Server.new(name: "my_server") # Default Streamable HTTP - session oriented transport = MCP::Server::Transports::StreamableHTTPTransport.new(server) server.transport = transport # When tools change, notify clients server.define_tool(name: "new_tool") { |**args| { result: "ok" } } server.notify_tools_list_changed ``` You can use Stateless Streamable HTTP, where notifications are not supported and all calls are request/response interactions. This mode allows for easy multi-node deployment. Set `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new` (`stateless` defaults to `false`): ```ruby # Stateless Streamable HTTP - session-less transport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true) ``` ### Unsupported Features (to be implemented in future versions) - Log Level - Resource subscripti