Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion Gemfile
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ gemspec

group :development do
if RUBY_VERSION >= "3.1.0"
gem "mcp", "~> 0.7"
gem "event_stream_parser", ">= 1"
gem "faraday", ">= 2"
gem "mcp", "~> 0.25"
end

# Development dependencies
Expand Down
10 changes: 7 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ RubyLLM::MCP is a Ruby client for the [Model Context Protocol (MCP)](https://mod

Use MCP tools, resources, and prompts from your RubyLLM chats over `stdio`, streamable HTTP, or SSE.

**Protocol support:** Fully supports MCP spec `2025-06-18` (stable), with draft spec `2026-01-26` available.
**Protocol support:** Fully supports MCP spec `2025-11-25` (stable), with draft spec `2026-01-26` available.

## RubyLLM::MCP Out of the Box

Expand All @@ -23,7 +23,7 @@ Our goal is to be able to plug MCP into Ruby/RubyLLM apps as easily as possible.
RubyLLM::MCP gives you that:

- Ruby-first API for using MCP tools, resources, and prompts directly in RubyLLM chat workflows
- Stable protocol track by default (`2025-06-18`), with opt-in draft track (`2026-01-26`)
- Stable protocol track by default (`2025-11-25`), with opt-in draft track (`2026-01-26`)
- Built-in notification and response handlers for real-time and interactive workflows
- MCP OAuth 2.1 authentication support (PKCE, dynamic registration, discovery, and automatic token refresh)
- OAuth setup paths for Rails apps (per-user connections) and browser-based CLI flows
Expand Down Expand Up @@ -154,7 +154,11 @@ bundle install
If you want the official SDK adapter, also add:

```ruby
gem "mcp", "~> 0.7"
gem "mcp", "~> 0.25"

# Also required when mcp_sdk uses Streamable HTTP
gem "faraday", ">= 2"
gem "event_stream_parser", ">= 1"
```

## Rails
Expand Down
2 changes: 2 additions & 0 deletions docs/client/elicitation.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ description: "MCP elicitation - allow servers to request additional structured i

Elicitation allows MCP servers to request additional structured information from users during interactions. This enables dynamic workflows where servers can ask for clarification, gather additional context, or collect user preferences in real-time.

Elicitation is available through the native adapter's supported transports and through `:mcp_sdk` Streamable HTTP. Official SDK stdio does not expose server-request handlers in version 0.25.

## Table of contents
{: .no_toc .text-delta }

Expand Down
2 changes: 2 additions & 0 deletions docs/client/sampling.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ description: "MCP sampling - allow servers to use your LLM for their own request

MCP sampling allows servers to offload LLM requests to your client rather than making them directly. This enables servers to use your LLM connections and configurations while maintaining their own logic and workflows.

Sampling is available through the native adapter's supported transports and through `:mcp_sdk` Streamable HTTP. Official SDK stdio does not expose server-request handlers in version 0.25.

## Table of contents
{: .no_toc .text-delta }

Expand Down
23 changes: 13 additions & 10 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,14 +97,15 @@ end
### Adapter Options

**`:ruby_llm`** (default)
- Full MCP protocol implementation
- All transport types (stdio, SSE, HTTP)
- Advanced features (sampling, roots, progress tracking, etc.)
- Independent RubyLLM::MCP protocol implementation and transports
- Stdio, legacy SSE, and Streamable HTTP
- Full notification-oriented feature set, roots, subscriptions, progress, tasks, sampling, and elicitation

**`:mcp_sdk`**
- Official Anthropic-maintained SDK
- Core features only (tools, resources, prompts)
- Limited transport support (stdio, HTTP - no SSE)
- Official Model Context Protocol Ruby SDK 0.25
- Official stdio and Streamable HTTP transports only
- Tools, resources, prompts, templates, completions, pagination, structured output, cache hints, and extensions
- HTTP additionally supports official OAuth providers, sampling, and elicitation

See the [Adapters Guide]({% link guides/adapters.md %}) for detailed feature comparison and usage examples.

Expand Down Expand Up @@ -442,7 +443,7 @@ The RubyLLM MCP client supports multiple protocol versions. You can access these
```ruby
# Latest supported protocol version
puts RubyLLM::MCP::Native::Protocol.latest_version
# => "2025-06-18"
# => "2025-11-25"

# Draft protocol version (opt-in)
puts RubyLLM::MCP::Native::Protocol.draft_version
Expand All @@ -454,7 +455,7 @@ puts RubyLLM::MCP::Native::Protocol.default_negotiated_version

# All supported versions
puts RubyLLM::MCP::Native::Protocol.supported_versions
# => ["2026-01-26", "2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"]
# => ["2026-01-26", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"]

# Check if a version is supported
RubyLLM::MCP::Native::Protocol.supported_version?("2025-06-18")
Expand All @@ -466,7 +467,8 @@ RubyLLM::MCP::Native::Protocol.supported_version?("2025-06-18")
Different protocol versions support different features:

- **2026-01-26** (Draft, opt-in): Draft extension negotiation path
- **2025-06-18** (Latest): Structured tool output, OAuth authentication, elicitation support, resource links, enhanced metadata
- **2025-11-25** (Latest stable): Current stable lifecycle and client/server feature set
- **2025-06-18**: Structured tool output, OAuth authentication, elicitation support, resource links, enhanced metadata
- **2025-03-26** (Default): Tool calling, resources, prompts, completions, notifications
- **2024-11-05**: Basic tool and resource support
- **2024-10-07**: Initial MCP implementation
Expand Down Expand Up @@ -516,7 +518,8 @@ Notes:
- Outbound extension advertisement uses canonical ID `io.modelcontextprotocol/ui`
- Alias `io.modelcontextprotocol/apps` is accepted for inbound capability reads and config merge
- Extension advertisement is supported on stable `2025-06-18+` and draft protocol versions
- `:mcp_sdk` accepts extension config in passive mode (no capability advertisement, one warning per process when configured)
- Both adapters advertise configured extensions on supported protocol versions
- The SDK adapter passes extension capabilities through its official `connect` handshake

For architecture and MCP Apps metadata details, see **[Client Extensions]({% link extensions/index.md %})** and **[MCP Apps]({% link extensions/mcp-apps.md %})**.

Expand Down
2 changes: 1 addition & 1 deletion docs/extensions/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Extension advertisement is protocol-version aware.
## Adapter Modes

- `:ruby_llm` adapter: **full** extension mode (`capabilities.extensions` advertised when protocol supports it)
- `:mcp_sdk` adapter: **passive** extension mode (config accepted, metadata parsing still works, no extension capability advertisement)
- `:mcp_sdk` adapter: **full** extension mode through the official 0.25 `connect` handshake

## Next Steps

Expand Down
4 changes: 2 additions & 2 deletions docs/extensions/mcp-apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,8 @@ puts meta.permissions.inspect
## Adapter Notes

- `:ruby_llm` and `:mcp_sdk` both expose parsed `apps_metadata`
- Only `:ruby_llm` advertises extension capabilities in full mode
- `:mcp_sdk` remains passive for capability advertisement
- Both adapters expose parsed metadata and advertise extension capabilities on supported protocol versions
- `:mcp_sdk` delegates negotiation to the official SDK 0.25 lifecycle

## Practical Flow

Expand Down
6 changes: 3 additions & 3 deletions docs/getting-started/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ The same client API can then be extended with resources, prompts, notifications,

1. **RubyLLM Chat** - Your application chat/session logic
2. **RubyLLM MCP Client** - Connection and protocol wrapper
3. **Adapter** - `:ruby_llm` (full) or `:mcp_sdk` (core/passive extensions)
3. **Adapter** - `:ruby_llm` (native implementation/transports) or `:mcp_sdk` (official SDK 0.25/transports)
4. **Transport** - `stdio`, `streamable`, `sse`
5. **MCP Server** - External capability provider

Expand All @@ -81,9 +81,9 @@ Use synchronous responses for short operations, notifications for real-time stat
RubyLLM MCP supports two adapters:

- **Native (`:ruby_llm`)** - Full-featured implementation with advanced MCP capabilities (sampling, roots, notifications, progress, tasks, elicitation).
- **MCP SDK (`:mcp_sdk`)** - Official SDK-backed adapter focused on core surfaces (tools, resources, prompts, templates, logging).
- **MCP SDK (`:mcp_sdk`)** - Official SDK 0.25 adapter with tools, resources, prompts, templates, completions, pagination, structured output, extension negotiation, and HTTP sampling/elicitation/OAuth.

Choose `:ruby_llm` when you need full protocol coverage and advanced interactions. Choose `:mcp_sdk` when you only need core MCP surfaces and want SDK alignment.
Choose `:ruby_llm` for the project's established transports and full notification-oriented feature set. Choose `:mcp_sdk` when you want the official SDK lifecycle, stdio/Streamable HTTP transports, OAuth providers, and low-level SDK access.

For the full feature matrix, see **[Adapters & Transports]({% link guides/adapters.md %})**.

Expand Down
Loading
Loading