{"id":28264237,"url":"https://github.com/modelcontextprotocol/ruby-sdk","last_synced_at":"2026-02-21T04:04:21.970Z","repository":{"id":294213429,"uuid":"940241698","full_name":"modelcontextprotocol/ruby-sdk","owner":"modelcontextprotocol","description":"The official Ruby SDK for the Model Context Protocol. Maintained in collaboration with Shopify.","archived":false,"fork":false,"pushed_at":"2026-01-13T16:04:48.000Z","size":446,"stargazers_count":681,"open_issues_count":18,"forks_count":91,"subscribers_count":23,"default_branch":"main","last_synced_at":"2026-01-13T18:33:25.711Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/mcp","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/modelcontextprotocol.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-02-27T21:00:23.000Z","updated_at":"2026-01-13T16:04:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"e0a74c68-e963-4481-bb79-f6477b86f41d","html_url":"https://github.com/modelcontextprotocol/ruby-sdk","commit_stats":null,"previous_names":["modelcontextprotocol/ruby-sdk"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/modelcontextprotocol/ruby-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelcontextprotocol%2Fruby-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelcontextprotocol%2Fruby-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelcontextprotocol%2Fruby-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelcontextprotocol%2Fruby-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/modelcontextprotocol","download_url":"https://codeload.github.com/modelcontextprotocol/ruby-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/modelcontextprotocol%2Fruby-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28492034,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T00:50:05.742Z","status":"ssl_error","status_checked_at":"2026-01-17T00:43:11.982Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-20T09:10:16.310Z","updated_at":"2026-01-17T01:58:22.832Z","avatar_url":"https://github.com/modelcontextprotocol.png","language":"Ruby","readme":"# MCP Ruby SDK [![Gem Version](https://img.shields.io/gem/v/mcp)](https://rubygems.org/gems/mcp) [![Apache 2.0 licensed](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/modelcontextprotocol/ruby-sdk/blob/main/LICENSE) [![CI](https://github.com/modelcontextprotocol/ruby-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/modelcontextprotocol/ruby-sdk/actions/workflows/ci.yml)\n\nThe official Ruby SDK for Model Context Protocol servers and clients.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'mcp'\n```\n\nAnd then execute:\n\n```console\n$ bundle install\n```\n\nOr install it yourself as:\n\n```console\n$ gem install mcp\n```\n\nYou may need to add additional dependencies depending on which features you wish to access.\n\n## Building an MCP Server\n\nThe `MCP::Server` class is the core component that handles JSON-RPC requests and responses.\nIt implements the Model Context Protocol specification, handling model context requests and responses.\n\n### Key Features\n\n- Implements JSON-RPC 2.0 message handling\n- Supports protocol initialization and capability negotiation\n- Manages tool registration and invocation\n- Supports prompt registration and execution\n- Supports resource registration and retrieval\n- Supports stdio \u0026 Streamable HTTP (including SSE) transports\n- Supports notifications for list changes (tools, prompts, resources)\n\n### Supported Methods\n\n- `initialize` - Initializes the protocol and returns server capabilities\n- `ping` - Simple health check\n- `tools/list` - Lists all registered tools and their schemas\n- `tools/call` - Invokes a specific tool with provided arguments\n- `prompts/list` - Lists all registered prompts and their schemas\n- `prompts/get` - Retrieves a specific prompt by name\n- `resources/list` - Lists all registered resources and their schemas\n- `resources/read` - Retrieves a specific resource by name\n- `resources/templates/list` - Lists all registered resource templates and their schemas\n\n### Custom Methods\n\nThe server allows you to define custom JSON-RPC methods beyond the standard MCP protocol methods using the `define_custom_method` method:\n\n```ruby\nserver = MCP::Server.new(name: \"my_server\")\n\n# Define a custom method that returns a result\nserver.define_custom_method(method_name: \"add\") do |params|\n  params[:a] + params[:b]\nend\n\n# Define a custom notification method (returns nil)\nserver.define_custom_method(method_name: \"notify\") do |params|\n  # Process notification\n  nil\nend\n```\n\n**Key Features:**\n\n- Accepts any method name as a string\n- Block receives the request parameters as a hash\n- Can handle both regular methods (with responses) and notifications\n- Prevents overriding existing MCP protocol methods\n- Supports instrumentation callbacks for monitoring\n\n**Usage Example:**\n\n```ruby\n# Client request\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"add\",\n  \"params\": { \"a\": 5, \"b\": 3 }\n}\n\n# Server response\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": 8\n}\n```\n\n**Error Handling:**\n\n- Raises `MCP::Server::MethodAlreadyDefinedError` if trying to override an existing method\n- Supports the same exception reporting and instrumentation as standard methods\n\n### Notifications\n\nThe server supports sending notifications to clients when lists of tools, prompts, or resources change. This enables real-time updates without polling.\n\n#### Notification Methods\n\nThe server provides three notification methods:\n\n- `notify_tools_list_changed` - Send a notification when the tools list changes\n- `notify_prompts_list_changed` - Send a notification when the prompts list changes\n- `notify_resources_list_changed` - Send a notification when the resources list changes\n\n#### Notification Format\n\nNotifications follow the JSON-RPC 2.0 specification and use these method names:\n\n- `notifications/tools/list_changed`\n- `notifications/prompts/list_changed`\n- `notifications/resources/list_changed`\n\n#### Transport Support\n\n- **stdio**: Notifications are sent as JSON-RPC 2.0 messages to stdout\n- **Streamable HTTP**: Notifications are sent as JSON-RPC 2.0 messages over HTTP with streaming (chunked transfer or SSE)\n\n#### Usage Example\n\n```ruby\nserver = MCP::Server.new(name: \"my_server\")\n\n# Default Streamable HTTP - session oriented\ntransport = MCP::Server::Transports::StreamableHTTPTransport.new(server)\n\nserver.transport = transport\n\n# When tools change, notify clients\nserver.define_tool(name: \"new_tool\") { |**args| { result: \"ok\" } }\nserver.notify_tools_list_changed\n```\n\nYou can use Stateless Streamable HTTP, where notifications are not supported and all calls are request/response interactions.\nThis mode allows for easy multi-node deployment.\nSet `stateless: true` in `MCP::Server::Transports::StreamableHTTPTransport.new` (`stateless` defaults to `false`):\n\n```ruby\n# Stateless Streamable HTTP - session-less\ntransport = MCP::Server::Transports::StreamableHTTPTransport.new(server, stateless: true)\n```\n\n### Unsupported Features (to be implemented in future versions)\n\n- Log Level\n- Resource subscriptions\n- Completions\n- Elicitation\n\n### Usage\n\n#### Rails Controller\n\nWhen added to a Rails controller on a route that handles POST requests, your server will be compliant with non-streaming\n[Streamable HTTP](https://modelcontextprotocol.io/specification/latest/basic/transports#streamable-http) transport\nrequests.\n\nYou can use the `Server#handle_json` method to handle requests.\n\n```ruby\nclass ApplicationController \u003c ActionController::Base\n  def index\n    server = MCP::Server.new(\n      name: \"my_server\",\n      title: \"Example Server Display Name\",\n      version: \"1.0.0\",\n      instructions: \"Use the tools of this server as a last resort\",\n      tools: [SomeTool, AnotherTool],\n      prompts: [MyPrompt],\n      server_context: { user_id: current_user.id },\n    )\n    render(json: server.handle_json(request.body.read))\n  end\nend\n```\n\n#### Stdio Transport\n\nIf you want to build a local command-line application, you can use the stdio transport:\n\n```ruby\nrequire \"mcp\"\n\n# Create a simple tool\nclass ExampleTool \u003c MCP::Tool\n  description \"A simple example tool that echoes back its arguments\"\n  input_schema(\n    properties: {\n      message: { type: \"string\" },\n    },\n    required: [\"message\"]\n  )\n\n  class \u003c\u003c self\n    def call(message:, server_context:)\n      MCP::Tool::Response.new([{\n        type: \"text\",\n        text: \"Hello from example tool! Message: #{message}\",\n      }])\n    end\n  end\nend\n\n# Set up the server\nserver = MCP::Server.new(\n  name: \"example_server\",\n  tools: [ExampleTool],\n)\n\n# Create and start the transport\ntransport = MCP::Server::Transports::StdioTransport.new(server)\ntransport.open\n```\n\nYou can run this script and then type in requests to the server at the command line.\n\n```console\n$ ruby examples/stdio_server.rb\n{\"jsonrpc\":\"2.0\",\"id\":\"1\",\"method\":\"ping\"}\n{\"jsonrpc\":\"2.0\",\"id\":\"2\",\"method\":\"tools/list\"}\n{\"jsonrpc\":\"2.0\",\"id\":\"3\",\"method\":\"tools/call\",\"params\":{\"name\":\"example_tool\",\"arguments\":{\"message\":\"Hello\"}}}\n```\n\n### Configuration\n\nThe gem can be configured using the `MCP.configure` block:\n\n```ruby\nMCP.configure do |config|\n  config.exception_reporter = -\u003e(exception, server_context) {\n    # Your exception reporting logic here\n    # For example with Bugsnag:\n    Bugsnag.notify(exception) do |report|\n      report.add_metadata(:model_context_protocol, server_context)\n    end\n  }\n\n  config.instrumentation_callback = -\u003e(data) {\n    puts \"Got instrumentation data #{data.inspect}\"\n  }\nend\n```\n\nor by creating an explicit configuration and passing it into the server.\nThis is useful for systems where an application hosts more than one MCP server but\nthey might require different instrumentation callbacks.\n\n```ruby\nconfiguration = MCP::Configuration.new\nconfiguration.exception_reporter = -\u003e(exception, server_context) {\n  # Your exception reporting logic here\n  # For example with Bugsnag:\n  Bugsnag.notify(exception) do |report|\n    report.add_metadata(:model_context_protocol, server_context)\n  end\n}\n\nconfiguration.instrumentation_callback = -\u003e(data) {\n  puts \"Got instrumentation data #{data.inspect}\"\n}\n\nserver = MCP::Server.new(\n  # ... all other options\n  configuration:,\n)\n```\n\n### Server Context and Configuration Block Data\n\n#### `server_context`\n\nThe `server_context` is a user-defined hash that is passed into the server instance and made available to tools, prompts, and exception/instrumentation callbacks. It can be used to provide contextual information such as authentication state, user IDs, or request-specific data.\n\n**Type:**\n\n```ruby\nserver_context: { [String, Symbol] =\u003e Any }\n```\n\n**Example:**\n\n```ruby\nserver = MCP::Server.new(\n  name: \"my_server\",\n  server_context: { user_id: current_user.id, request_id: request.uuid }\n)\n```\n\nThis hash is then passed as the `server_context` argument to tool and prompt calls, and is included in exception and instrumentation callbacks.\n\n#### Configuration Block Data\n\n##### Exception Reporter\n\nThe exception reporter receives:\n\n- `exception`: The Ruby exception object that was raised\n- `server_context`: The context hash provided to the server\n\n**Signature:**\n\n```ruby\nexception_reporter = -\u003e(exception, server_context) { ... }\n```\n\n##### Instrumentation Callback\n\nThe instrumentation callback receives a hash with the following possible keys:\n\n- `method`: (String) The protocol method called (e.g., \"ping\", \"tools/list\")\n- `tool_name`: (String, optional) The name of the tool called\n- `prompt_name`: (String, optional) The name of the prompt called\n- `resource_uri`: (String, optional) The URI of the resource called\n- `error`: (String, optional) Error code if a lookup failed\n- `duration`: (Float) Duration of the call in seconds\n\n**Type:**\n\n```ruby\ninstrumentation_callback = -\u003e(data) { ... }\n# where data is a Hash with keys as described above\n```\n\n**Example:**\n\n```ruby\nconfig.instrumentation_callback = -\u003e(data) {\n  puts \"Instrumentation: #{data.inspect}\"\n}\n```\n\n### Server Protocol Version\n\nThe server's protocol version can be overridden using the `protocol_version` keyword argument:\n\n```ruby\nconfiguration = MCP::Configuration.new(protocol_version: \"2024-11-05\")\nMCP::Server.new(name: \"test_server\", configuration: configuration)\n```\n\nIf no protocol version is specified, the latest stable version will be applied by default.\nThe latest stable version includes new features from the [draft version](https://modelcontextprotocol.io/specification/draft).\n\nThis will make all new server instances use the specified protocol version instead of the default version. The protocol version can be reset to the default by setting it to `nil`:\n\n```ruby\nMCP::Configuration.new(protocol_version: nil)\n```\n\nIf an invalid `protocol_version` value is set, an `ArgumentError` is raised.\n\nBe sure to check the [MCP spec](https://modelcontextprotocol.io/specification/versioning) for the protocol version to understand the supported features for the version being set.\n\n### Exception Reporting\n\nThe exception reporter receives two arguments:\n\n- `exception`: The Ruby exception object that was raised\n- `server_context`: A hash containing contextual information about where the error occurred\n\nThe server_context hash includes:\n\n- For tool calls: `{ tool_name: \"name\", arguments: { ... } }`\n- For general request handling: `{ request: { ... } }`\n\nWhen an exception occurs:\n\n1. The exception is reported via the configured reporter\n2. For tool calls, a generic error response is returned to the client: `{ error: \"Internal error occurred\", isError: true }`\n3. For other requests, the exception is re-raised after reporting\n\nIf no exception reporter is configured, a default no-op reporter is used that silently ignores exceptions.\n\n### Tools\n\nMCP spec includes [Tools](https://modelcontextprotocol.io/specification/latest/server/tools) which provide functionality to LLM apps.\n\nThis gem provides a `MCP::Tool` class that can be used to create tools in three ways:\n\n1. As a class definition:\n\n```ruby\nclass MyTool \u003c MCP::Tool\n  title \"My Tool\"\n  description \"This tool performs specific functionality...\"\n  input_schema(\n    properties: {\n      message: { type: \"string\" },\n    },\n    required: [\"message\"]\n  )\n  output_schema(\n    properties: {\n      result: { type: \"string\" },\n      success: { type: \"boolean\" },\n      timestamp: { type: \"string\", format: \"date-time\" }\n    },\n    required: [\"result\", \"success\", \"timestamp\"]\n  )\n  annotations(\n    read_only_hint: true,\n    destructive_hint: false,\n    idempotent_hint: true,\n    open_world_hint: false,\n    title: \"My Tool\"\n  )\n\n  def self.call(message:, server_context:)\n    MCP::Tool::Response.new([{ type: \"text\", text: \"OK\" }])\n  end\nend\n\ntool = MyTool\n```\n\n2. By using the `MCP::Tool.define` method with a block:\n\n```ruby\ntool = MCP::Tool.define(\n  name: \"my_tool\",\n  title: \"My Tool\",\n  description: \"This tool performs specific functionality...\",\n  annotations: {\n    read_only_hint: true,\n    title: \"My Tool\"\n  }\n) do |args, server_context:|\n  MCP::Tool::Response.new([{ type: \"text\", text: \"OK\" }])\nend\n```\n\n3. By using the `MCP::Server#define_tool` method with a block:\n\n```ruby\nserver = MCP::Server.new\nserver.define_tool(\n  name: \"my_tool\",\n  description: \"This tool performs specific functionality...\",\n  annotations: {\n    title: \"My Tool\",\n    read_only_hint: true\n  }\n) do |args, server_context:|\n  Tool::Response.new([{ type: \"text\", text: \"OK\" }])\nend\n```\n\nThe server_context parameter is the server_context passed into the server and can be used to pass per request information,\ne.g. around authentication state.\n\n### Tool Annotations\n\nTools can include annotations that provide additional metadata about their behavior. The following annotations are supported:\n\n- `destructive_hint`: Indicates if the tool performs destructive operations. Defaults to true\n- `idempotent_hint`: Indicates if the tool's operations are idempotent. Defaults to false\n- `open_world_hint`: Indicates if the tool operates in an open world context. Defaults to true\n- `read_only_hint`: Indicates if the tool only reads data (doesn't modify state). Defaults to false\n- `title`: A human-readable title for the tool\n\nAnnotations can be set either through the class definition using the `annotations` class method or when defining a tool using the `define` method.\n\n\u003e [!NOTE]\n\u003e This **Tool Annotations** feature is supported starting from `protocol_version: '2025-03-26'`.\n\n### Tool Output Schemas\n\nTools can optionally define an `output_schema` to specify the expected structure of their results. This works similarly to how `input_schema` is defined and can be used in three ways:\n\n1. **Class definition with output_schema:**\n\n```ruby\nclass WeatherTool \u003c MCP::Tool\n  tool_name \"get_weather\"\n  description \"Get current weather for a location\"\n\n  input_schema(\n    properties: {\n      location: { type: \"string\" },\n      units: { type: \"string\", enum: [\"celsius\", \"fahrenheit\"] }\n    },\n    required: [\"location\"]\n  )\n\n  output_schema(\n    properties: {\n      temperature: { type: \"number\" },\n      condition: { type: \"string\" },\n      humidity: { type: \"integer\" }\n    },\n    required: [\"temperature\", \"condition\", \"humidity\"]\n  )\n\n  def self.call(location:, units: \"celsius\", server_context:)\n    # Call weather API and structure the response\n    api_response = WeatherAPI.fetch(location, units)\n    weather_data = {\n      temperature: api_response.temp,\n      condition: api_response.description,\n      humidity: api_response.humidity_percent\n    }\n\n    output_schema.validate_result(weather_data)\n\n    MCP::Tool::Response.new([{\n      type: \"text\",\n      text: weather_data.to_json\n    }])\n  end\nend\n```\n\n2. **Using Tool.define with output_schema:**\n\n```ruby\ntool = MCP::Tool.define(\n  name: \"calculate_stats\",\n  description: \"Calculate statistics for a dataset\",\n  input_schema: {\n    properties: {\n      numbers: { type: \"array\", items: { type: \"number\" } }\n    },\n    required: [\"numbers\"]\n  },\n  output_schema: {\n    properties: {\n      mean: { type: \"number\" },\n      median: { type: \"number\" },\n      count: { type: \"integer\" }\n    },\n    required: [\"mean\", \"median\", \"count\"]\n  }\n) do |args, server_context:|\n  # Calculate statistics and validate against schema\n  MCP::Tool::Response.new([{ type: \"text\", text: \"Statistics calculated\" }])\nend\n```\n\n3. **Using OutputSchema objects:**\n\n```ruby\nclass DataTool \u003c MCP::Tool\n  output_schema MCP::Tool::OutputSchema.new(\n    properties: {\n      success: { type: \"boolean\" },\n      data: { type: \"object\" }\n    },\n    required: [\"success\"]\n  )\nend\n```\n\nOutput schema may also describe an array of objects:\n\n```ruby\nclass WeatherTool \u003c MCP::Tool\n  output_schema(\n    type: \"array\",\n    items: {\n      properties: {\n        temperature: { type: \"number\" },\n        condition: { type: \"string\" },\n        humidity: { type: \"integer\" }\n      },\n      required: [\"temperature\", \"condition\", \"humidity\"]\n    }\n  )\nend\n```\n\nPlease note: in this case, you must provide `type: \"array\"`. The default type\nfor output schemas is `object`.\n\nMCP spec for the [Output Schema](https://modelcontextprotocol.io/specification/latest/server/tools#output-schema) specifies that:\n\n- **Server Validation**: Servers MUST provide structured results that conform to the output schema\n- **Client Validation**: Clients SHOULD validate structured results against the output schema\n- **Better Integration**: Enables strict schema validation, type information, and improved developer experience\n- **Backward Compatibility**: Tools returning structured content SHOULD also include serialized JSON in a TextContent block\n\nThe output schema follows standard JSON Schema format and helps ensure consistent data exchange between MCP servers and clients.\n\n### Tool Responses with Structured Content\n\nTools can return structured data alongside text content using the `structured_content` parameter.\n\nThe structured content will be included in the JSON-RPC response as the `structuredContent` field.\n\n```ruby\nclass WeatherTool \u003c MCP::Tool\n  description \"Get current weather and return structured data\"\n\n  def self.call(location:, units: \"celsius\", server_context:)\n    # Call weather API and structure the response\n    api_response = WeatherAPI.fetch(location, units)\n    weather_data = {\n      temperature: api_response.temp,\n      condition: api_response.description,\n      humidity: api_response.humidity_percent\n    }\n\n    output_schema.validate_result(weather_data)\n\n    MCP::Tool::Response.new(\n      [{\n        type: \"text\",\n        text: weather_data.to_json\n      }],\n      structured_content: weather_data\n    )\n  end\nend\n```\n\n### Tool Responses with Errors\n\nTools can return error information alongside text content using the `error` parameter.\n\nThe error will be included in the JSON-RPC response as the `isError` field.\n\n```ruby\nclass WeatherTool \u003c MCP::Tool\n  description \"Get current weather and return structured data\"\n\n  def self.call(server_context:)\n    # Do something here\n    content = {}\n\n    MCP::Tool::Response.new(\n      [{\n        type: \"text\",\n        text: content.to_json\n      }],\n      structured_content: content,\n      error: true\n    )\n  end\nend\n```\n\n### Prompts\n\nMCP spec includes [Prompts](https://modelcontextprotocol.io/specification/latest/server/prompts), which enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs.\n\nThe `MCP::Prompt` class provides three ways to create prompts:\n\n1. As a class definition with metadata:\n\n```ruby\nclass MyPrompt \u003c MCP::Prompt\n  prompt_name \"my_prompt\"  # Optional - defaults to underscored class name\n  title \"My Prompt\"\n  description \"This prompt performs specific functionality...\"\n  arguments [\n    MCP::Prompt::Argument.new(\n      name: \"message\",\n      title: \"Message Title\",\n      description: \"Input message\",\n      required: true\n    )\n  ]\n  meta({ version: \"1.0\", category: \"example\" })\n\n  class \u003c\u003c self\n    def template(args, server_context:)\n      MCP::Prompt::Result.new(\n        description: \"Response description\",\n        messages: [\n          MCP::Prompt::Message.new(\n            role: \"user\",\n            content: MCP::Content::Text.new(\"User message\")\n          ),\n          MCP::Prompt::Message.new(\n            role: \"assistant\",\n            content: MCP::Content::Text.new(args[\"message\"])\n          )\n        ]\n      )\n    end\n  end\nend\n\nprompt = MyPrompt\n```\n\n2. Using the `MCP::Prompt.define` method:\n\n```ruby\nprompt = MCP::Prompt.define(\n  name: \"my_prompt\",\n  title: \"My Prompt\",\n  description: \"This prompt performs specific functionality...\",\n  arguments: [\n    MCP::Prompt::Argument.new(\n      name: \"message\",\n      title: \"Message Title\",\n      description: \"Input message\",\n      required: true\n    )\n  ],\n  meta: { version: \"1.0\", category: \"example\" }\n) do |args, server_context:|\n  MCP::Prompt::Result.new(\n    description: \"Response description\",\n    messages: [\n      MCP::Prompt::Message.new(\n        role: \"user\",\n        content: MCP::Content::Text.new(\"User message\")\n      ),\n      MCP::Prompt::Message.new(\n        role: \"assistant\",\n        content: MCP::Content::Text.new(args[\"message\"])\n      )\n    ]\n  )\nend\n```\n\n3. Using the `MCP::Server#define_prompt` method:\n\n```ruby\nserver = MCP::Server.new\nserver.define_prompt(\n  name: \"my_prompt\",\n  description: \"This prompt performs specific functionality...\",\n  arguments: [\n    Prompt::Argument.new(\n      name: \"message\",\n      title: \"Message Title\",\n      description: \"Input message\",\n      required: true\n    )\n  ],\n  meta: { version: \"1.0\", category: \"example\" }\n) do |args, server_context:|\n  Prompt::Result.new(\n    description: \"Response description\",\n    messages: [\n      Prompt::Message.new(\n        role: \"user\",\n        content: Content::Text.new(\"User message\")\n      ),\n      Prompt::Message.new(\n        role: \"assistant\",\n        content: Content::Text.new(args[\"message\"])\n      )\n    ]\n  )\nend\n```\n\nThe server_context parameter is the server_context passed into the server and can be used to pass per request information,\ne.g. around authentication state or user preferences.\n\n### Key Components\n\n- `MCP::Prompt::Argument` - Defines input parameters for the prompt template with name, title, description, and required flag\n- `MCP::Prompt::Message` - Represents a message in the conversation with a role and content\n- `MCP::Prompt::Result` - The output of a prompt template containing description and messages\n- `MCP::Content::Text` - Text content for messages\n\n### Usage\n\nRegister prompts with the MCP server:\n\n```ruby\nserver = MCP::Server.new(\n  name: \"my_server\",\n  prompts: [MyPrompt],\n  server_context: { user_id: current_user.id },\n)\n```\n\nThe server will handle prompt listing and execution through the MCP protocol methods:\n\n- `prompts/list` - Lists all registered prompts and their schemas\n- `prompts/get` - Retrieves and executes a specific prompt with arguments\n\n### Instrumentation\n\nThe server allows registering a callback to receive information about instrumentation.\nTo register a handler pass a proc/lambda to as `instrumentation_callback` into the server constructor.\n\n```ruby\nMCP.configure do |config|\n  config.instrumentation_callback = -\u003e(data) {\n    puts \"Got instrumentation data #{data.inspect}\"\n  }\nend\n```\n\nThe data contains the following keys:\n\n- `method`: the method called, e.g. `ping`, `tools/list`, `tools/call` etc\n- `tool_name`: the name of the tool called\n- `prompt_name`: the name of the prompt called\n- `resource_uri`: the uri of the resource called\n- `error`: if looking up tools/prompts etc failed, e.g. `tool_not_found`\n- `duration`: the duration of the call in seconds\n\n`tool_name`, `prompt_name` and `resource_uri` are only populated if a matching handler is registered.\nThis is to avoid potential issues with metric cardinality\n\n### Resources\n\nMCP spec includes [Resources](https://modelcontextprotocol.io/specification/latest/server/resources).\n\n### Reading Resources\n\nThe `MCP::Resource` class provides a way to register resources with the server.\n\n```ruby\nresource = MCP::Resource.new(\n  uri: \"https://example.com/my_resource\",\n  name: \"my-resource\",\n  title: \"My Resource\",\n  description: \"Lorem ipsum dolor sit amet\",\n  mime_type: \"text/html\",\n)\n\nserver = MCP::Server.new(\n  name: \"my_server\",\n  resources: [resource],\n)\n```\n\nThe server must register a handler for the `resources/read` method to retrieve a resource dynamically.\n\n```ruby\nserver.resources_read_handler do |params|\n  [{\n    uri: params[:uri],\n    mimeType: \"text/plain\",\n    text: \"Hello from example resource! URI: #{params[:uri]}\"\n  }]\nend\n```\n\notherwise `resources/read` requests will be a no-op.\n\n### Resource Templates\n\nThe `MCP::ResourceTemplate` class provides a way to register resource templates with the server.\n\n```ruby\nresource_template = MCP::ResourceTemplate.new(\n  uri_template: \"https://example.com/my_resource_template\",\n  name: \"my-resource-template\",\n  title: \"My Resource Template\",\n  description: \"Lorem ipsum dolor sit amet\",\n  mime_type: \"text/html\",\n)\n\nserver = MCP::Server.new(\n  name: \"my_server\",\n  resource_templates: [resource_template],\n)\n```\n\n## Building an MCP Client\n\nThe `MCP::Client` class provides an interface for interacting with MCP servers.\n\nThis class supports:\n\n- Tool listing via the `tools/list` method (`MCP::Client#tools`)\n- Tool invocation via the `tools/call` method (`MCP::Client#call_tools`)\n- Resource listing via the `resources/list` method (`MCP::Client#resources`)\n- Resource reading via the `resources/read` method (`MCP::Client#read_resources`)\n- Prompt listing via the `prompts/list` method (`MCP::Client#prompts`)\n- Prompt retrieval via the `prompts/get` method (`MCP::Client#get_prompt`)\n- Automatic JSON-RPC 2.0 message formatting\n- UUID request ID generation\n\nClients are initialized with a transport layer instance that handles the low-level communication mechanics.\nAuthorization is handled by the transport layer.\n\n## Transport Layer Interface\n\nIf the transport layer you need is not included in the gem, you can build and pass your own instances so long as they conform to the following interface:\n\n```ruby\nclass CustomTransport\n  # Sends a JSON-RPC request to the server and returns the raw response.\n  #\n  # @param request [Hash] A complete JSON-RPC request object.\n  #     https://www.jsonrpc.org/specification#request_object\n  # @return [Hash] A hash modeling a JSON-RPC response object.\n  #     https://www.jsonrpc.org/specification#response_object\n  def send_request(request:)\n    # Your transport-specific logic here\n    # - HTTP: POST to endpoint with JSON body\n    # - WebSocket: Send message over WebSocket\n    # - stdio: Write to stdout, read from stdin\n    # - etc.\n  end\nend\n```\n\n### HTTP Transport Layer\n\nUse the `MCP::Client::HTTP` transport to interact with MCP servers using simple HTTP requests.\n\nYou'll need to add `faraday` as a dependency in order to use the HTTP transport layer:\n\n```ruby\ngem 'mcp'\ngem 'faraday', '\u003e= 2.0'\n```\n\nExample usage:\n\n```ruby\nhttp_transport = MCP::Client::HTTP.new(url: \"https://api.example.com/mcp\")\nclient = MCP::Client.new(transport: http_transport)\n\n# List available tools\ntools = client.tools\ntools.each do |tool|\n  puts \u003c\u003c~TOOL_INFORMATION\n    Tool: #{tool.name}\n    Description: #{tool.description}\n    Input Schema: #{tool.input_schema}\n  TOOL_INFORMATION\nend\n\n# Call a specific tool\nresponse = client.call_tool(\n  tool: tools.first,\n  arguments: { message: \"Hello, world!\" }\n)\n```\n\n#### HTTP Authorization\n\nBy default, the HTTP transport layer provides no authentication to the server, but you can provide custom headers if you need authentication. For example, to use Bearer token authentication:\n\n```ruby\nhttp_transport = MCP::Client::HTTP.new(\n  url: \"https://api.example.com/mcp\",\n  headers: {\n    \"Authorization\" =\u003e \"Bearer my_token\"\n  }\n)\n\nclient = MCP::Client.new(transport: http_transport)\nclient.tools # will make the call using Bearer auth\n```\n\nYou can add any custom headers needed for your authentication scheme, or for any other purpose. The client will include these headers on every request.\n\n### Tool Objects\n\nThe client provides a wrapper class for tools returned by the server:\n\n- `MCP::Client::Tool` - Represents a single tool with its metadata\n\nThis class provides easy access to tool properties like name, description, input schema, and output schema.\n\n## Documentation\n\n- [SDK API documentation](https://rubydoc.info/gems/mcp)\n- [Model Context Protocol documentation](https://modelcontextprotocol.io)\n","funding_links":[],"categories":["📚 Projects (1974 total)","Ruby","Open Source","Mcp Server Directories \u0026 Lists","MCP Frameworks and libraries","📦 Other","SDKs"],"sub_categories":["MCP Servers","MCP","Ruby"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodelcontextprotocol%2Fruby-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodelcontextprotocol%2Fruby-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodelcontextprotocol%2Fruby-sdk/lists"}