MCP Ruby SDK: building Model Context Protocol servers and clients in Ruby

What the mcp gem actually solves for Ruby teams

The Model Context Protocol defines how an assistant host discovers and calls tools, prompts and resources exposed by a separate process. Implementing that wire format by hand means writing JSON-RPC framing, lifecycle negotiation, capability advertisement and transport plumbing before you write a single line of domain logic. The mcp gem removes that work. It is the official Ruby SDK, published as the mcp gem on RubyGems, and it targets two audiences: teams with existing Ruby or Rails code who want to expose it as tools, and teams who need a Ruby program to consume an MCP server written in any language. The README frames the scope as building servers that "expose tools, prompts, and resources to any MCP host" and clients that "connect to any MCP server, with automatic lifecycle negotiation and OAuth 2.1 authorization". That second clause matters. A client that handles the initialization handshake for you is the difference between a working integration and a weekend of reading the specification.

How the SDK is put together: tools, transports and lifecycle

The architecture separates protocol concerns from transport concerns. A server is an MCP::Server instance constructed with a name and a list of tool classes. Each tool subclasses MCP::Tool, declares a description and an input_schema, and implements a class-level call method that returns an MCP::Tool::Response. The server object itself knows nothing about how bytes move. That is the transport's job: MCP::Server::Transports::StdioTransport wraps the server and opens a stream over stdin and stdout, while the README points to Streamable HTTP, including SSE, as the other standard transport, with a documented path for mounting inside Rails. On the client side the same split appears. MCP::Client takes a transport object, either MCP::Client::Stdio for a subprocess or MCP::Client::HTTP for a remote endpoint, and the README is explicit that you must call client.connect before sending requests because that performs the initialization handshake. The feature list claims the full protocol surface: server-to-client requests, multi round-trip requests, notifications, progress, logging, cancellation, completions and pagination. The repository also carries a conformance/ directory and a dev.yml file, which suggests the maintainers test against protocol conformance rather than only their own examples.

Installing the mcp gem and calling your first tool

Add the gem to your Gemfile and install it. The README notes you may need additional dependencies depending on which features you use, so treat the base install as a starting point rather than a complete bundle.

gem "mcp"

$ bundle install

If you are not using Bundler, the README gives the direct install as `gem install mcp`. Next, write a server script. The README's quick start defines a single tool that echoes a message, wraps it in an MCP::Server with the name example_server, and opens a stdio transport. Save it as server.rb and run it with Ruby. Once running, the process reads JSON-RPC lines from stdin. The README shows three requests you can paste in: a ping, a tools/list call, and a tools/call against the example tool with a message argument. You should see a JSON-RPC response for each line. If nothing comes back, the transport is not receiving complete lines, which is the most common first failure with stdio servers. On the client side, the README spawns that same server as a subprocess using MCP::Client::Stdio with a command, an args array, an env hash and a read_timeout of 30, then calls client.connect, iterates client.tools, and calls client.call_tool with the tool and an arguments hash. Close the transport when finished.

Where the SDK stops short

The README is a quick start, not a reference. It does not document rollback behaviour, retry semantics, or what happens to in-flight requests when a transport closes mid-call. The read_timeout parameter on MCP::Client::Stdio is the only timeout the README shows, and it is not explained: whether it covers connection establishment, individual reads, or both is left to the API documentation at rubydoc.info. Teams running long-lived Streamable HTTP connections will need to answer that themselves. There is also a versioning question. The repository root contains VERSIONING.md and RELEASE.md, and three releases landed in the two weeks before 2026-09-10, so the surface is moving quickly. The README does not state a stability guarantee for the API, and nothing in it promises backward compatibility across minor versions. If your tool definitions are generated from another schema, pin the gem version and read VERSIONING.md before upgrading. Finally, this is Ruby only. If your team is polyglot and wants one SDK to cover services in three languages, the official Ruby SDK is the wrong layer to standardise on.

Choosing between the Ruby SDK and a language-agnostic MCP approach

The real alternative is not another Ruby gem. It is running an MCP server in a language with a different conformance story, or putting a thin protocol shim in front of an existing HTTP service. A Python or TypeScript MCP implementation lets you reuse a codebase that may already hold the tool logic, and both ecosystems have their own official SDKs under the same modelcontextprotocol organisation. The difference in approach is where the protocol code lives. With the Ruby SDK, the protocol code lives in your Ruby process, which means your tool classes can call ActiveRecord models, Sidekiq jobs or internal service objects directly, with no serialization boundary. With a shim, your Ruby application keeps its HTTP API and a separate process translates MCP calls into HTTP requests. That second design costs you a network hop and a second deployment unit, but it keeps the MCP surface out of your Rails process entirely. The Ruby SDK also ships a Rails example under examples/rails, which is the fastest way to judge whether the in-process model fits your application.

Maintenance, licensing and the cost of staying current

The repository is not archived, and the last push was on 2026-09-10, with v1.5.1 released on 2026-09-09. That is a fast release cadence, and it carries a real cost: you should expect to re-read the changelog and the API documentation more often than you would for a mature, slow-moving library. The repository root includes CHANGELOG.md, VERSIONING.md and RELEASE.md, so the project does document its own release process, but the README does not summarise it. On licensing, the README states the project is "licensed under the Apache License 2.0 for new contributions, with existing code under MIT", and directs readers to the LICENSE file for details. The repository's licence field is reported as NOASSERTION, which is a metadata artefact rather than a contradiction, but it means automated licence scanners may flag the package. If your organisation runs licence checks in CI, read LICENSE directly and confirm how the Apache 2.0 and MIT portions are delineated before you rely on a scanner's verdict. This is a description of what the files say, not legal advice.

Editorial conclusion

Adopt the mcp gem if you already run Ruby or Rails and want to expose existing domain logic as MCP tools without a second language in the stack, or if you need a Ruby client that speaks stdio and Streamable HTTP. Do not adopt it expecting multi-language polyglot support, a stable API guarantee, or a documented rollback path. Before you commit, read VERSIONING.md and RELEASE.md in the repository root, confirm the Apache 2.0 and MIT split described in LICENSE, and run the examples/stdio_server.rb script locally to see the JSON-RPC shapes your host will receive.

Frequently asked questions

Official sources

1. Issues
2. modelcontextprotocol/ruby-sdk on GitHub
3. Project website
4. README
5. Releases