Ruby Sdk

What ruby-sdk does

ruby-sdk is the official Ruby implementation of the Model Context Protocol for both sides of an MCP connection. Ruby applications can use it to expose tools, prompts, and resources to MCP hosts, or to connect to MCP servers and invoke their capabilities.

The SDK covers the protocol features needed for more than basic request and response handling. It includes lifecycle negotiation, server-to-client requests, multi-step exchanges, notifications, progress reporting, logging, cancellation, completions, and pagination. OAuth 2.1 support is available for protecting MCP servers as resource servers and for authorizing clients.

How it works

A server is assembled from Ruby classes and an MCP::Server instance. Tools define their descriptions, input schemas, and call behavior, then become available through a selected transport. A minimal stdio server reads JSON-RPC messages from standard input and writes responses to standard output.

Clients use a transport-specific implementation, such as MCP::Client::Stdio for spawning a local subprocess or MCP::Client::HTTP for connecting to a Streamable HTTP endpoint. After creating an MCP::Client, the application calls connect to negotiate the protocol lifecycle, lists available tools, and invokes a selected tool with arguments.

Streamable HTTP support also includes SSE. Servers can run independently or be mounted in a Rails application, making the SDK suitable for standalone Ruby processes and Rails-based MCP endpoints.

Setup and configuration

Add the gem to a Ruby application's Gemfile:

gem "mcp"

Run bundle install, or install the package directly with gem install mcp. Some optional SDK features may require additional dependencies.

A server needs a name, its available tools, and a transport. A client needs a transport configured with the command and arguments for a local server, or with the endpoint details for an HTTP server. The stdio client also accepts environment variables for the spawned process and a read timeout.

Runnable examples include a basic server and client as well as a complete Rails application. The SDK guides and API reference provide the detailed Ruby interfaces for server, client, and transport setup.

Tools and capabilities

• Define MCP tools with descriptions and input schemas.
• Expose prompts and resources from Ruby MCP servers.
• Connect to local subprocesses over stdio.
• Connect to remote endpoints over Streamable HTTP and SSE.
• Integrate an MCP server with Rails.
• Negotiate client and server lifecycles automatically.
• Support OAuth 2.1 authorization and resource-server protection.
• Handle progress, cancellation, notifications, logging, completions, pagination, and server-to-client requests.

Limitations and notes

The package is an SDK rather than a single turnkey MCP service: applications must define their own server capabilities or client behavior. Additional dependencies may be needed for selected features. New contributions are under Apache License 2.0, while existing code is under MIT, as described by the project license.