riffer 0.25.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55bd24093ac1af4a33163b95afc320f2f3326bf6105b8e55253e78bd0763551d
-  data.tar.gz: dc70e95bb46d2a7b51840299a2da6a4f79a27421791a06d18255c655afcd4cfe
+  metadata.gz: 7701c51a8dff2c1da03718cb852c86296ab738839163b86ddf46b5e4e78600da
+  data.tar.gz: f99baf1c378b7a8a8ce2ec8dad231cd01e70d25cee4a277c2d724c0377dfc56d
 SHA512:
-  metadata.gz: 992ab0a333cedb5107bc90fcf00f0d48151ea4cb09ceadb455dd80c95d06fd00ba6e005405b844f2857619f3a549dd0c8ff82939ea764db0b280fa22643f8511
-  data.tar.gz: 2de5d6c8add2a20442cf38d6d216384379fa270f115bc92cf81fa0ded554573de5a513694845615365fdb041308a8c2d830ab47044fbddf30e741c42107681c1
+  metadata.gz: 423051f85e8fb037526b5aa6500b57b86fa4106a8a701e673df868c216661245a31702d9fb1fb3602a249d0f57dbe074a439e4f5f7a121d6d0c1c945d771f42f
+  data.tar.gz: a52e8baf66cebd4dc522dc1d836325f35442272d3fb02146c153156cd1232f08ada5cc3dc968033badd65df599fd453fa882d479afecddac8512e3c7d5e12bad

data/.agents/architecture.md

@@ -40,7 +40,7 @@ Adapters for LLM APIs. The base class uses a template-method pattern — `genera
 
 Providers are registered in `Riffer::Providers::Repository::REPO` with identifiers (e.g., `openai`, `amazon_bedrock`).
 
-Each provider declares a preferred skill adapter via `self.skills_adapter` (Markdown for most, XML for Anthropic).
+Each provider declares a preferred skill adapter via `self.skills_adapter(model = nil)`. Default is Markdown; Anthropic returns XML; Amazon Bedrock returns XML when the model identifier matches an Anthropic model (e.g. `anthropic.claude-…` or `us.anthropic.claude-…`); Mock returns XML when the model name contains `claude`. The agent passes the resolved model identifier so proxy providers (Bedrock, Mock) can pick the right adapter without per-agent overrides.
 
 ### Skills (`lib/riffer/skills/`)
 
@@ -132,9 +132,35 @@ Built-in runtimes:
 
 Context flow: `Agent#execute_tool_calls` → `ToolRuntime#execute(tool_calls, tools:, context:)` → `Runner#map(tool_calls, context:) { dispatch }` → `Tool#call(context:, **args)`
 
+### MCP Integration (`lib/riffer/mcp/`)
+
+Register third-party MCP servers globally; agents opt-in by tag via `use_mcp`. Tags are application-defined (manifests may list several; any overlap with `use_mcp` opts in—see `docs/14_MCP.md`).
+
+```ruby
+Riffer::Mcp.register(
+  name: "github",
+  tags: [:github],
+  endpoint: "https://mcp.github.com",
+  discovery_headers: -> { {"Authorization" => "Bearer #{ENV['GITHUB_TOKEN']}"} }
+)
+
+# Optional: per-run tools/call headers (see docs/14_MCP.md)
+Riffer.configure { |c| c.mcp.credentials = ->(manifest:, matched_tags:, context:) { ... } }
+
+class ResearchAgent < Riffer::Agent
+  model "openai/gpt-5-mini"
+  use_mcp :github                      # picks up any :github-tagged registration
+  use_mcp :search, on_pending: :wait   # per-call override
+end
+```
+
+Key types: `Manifest` (`discovery_headers`, optional `credentials_scope` hint), `Registry` (thread-safe store), `Registration` (spawns discovery thread → `ToolFactory`), `Client` (wraps `mcp` gem), `AuthenticatedTool` (wraps MCP tools when `credentials` proc is set).
+
+**on_pending strategies** (global default `:ignore`): `:ignore` skips the server; `:wait` blocks until ready, re-raises failed discovery immediately, or times out; `:raise` re-raises failed discovery or `NotReadyError` while still pending.
+
 ## Key Patterns
 
-- Model config accepts a `provider/model` string (e.g., `openai/gpt-4`) or a Proc/lambda that returns one
+- Model config accepts a `provider/model` string (e.g., `openai/gpt-5-mini`) or a Proc/lambda that returns one
 - Configuration via `Riffer.configure { |c| c.openai.api_key = "..." }`
 - Providers use `depends_on` helper for runtime dependency checking
 - Zeitwerk for autoloading - file structure must match module/class names
@@ -199,6 +225,14 @@ lib/
       reasoning_done.rb  # Reasoning done event
       web_search_status.rb # Web search status event
       web_search_done.rb   # Web search done event
+    mcp.rb               # MCP public API + error classes
+    mcp/
+      manifest.rb        # Server config value object
+      registry.rb        # Thread-safe global store
+      registration.rb    # Per-server state + discovery thread
+      client.rb          # Thin mcp gem wrapper
+      authenticated_tool.rb  # Wraps MCP tools when credentials proc is configured
+      tool_factory.rb    # Generates Riffer::Tool subclasses from MCP tools
 test/
   test_helper.rb         # Minitest configuration with VCR
   riffer_test.rb         # Main module tests

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.25.0"
+  ".": "0.27.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.27.0](https://github.com/janeapp/riffer/compare/riffer/v0.26.0...riffer/v0.27.0) (2026-05-01)
+
+
+### Features
+
+* integrate MCP server tools into agent tool resolution ([6c7a09a](https://github.com/janeapp/riffer/commit/6c7a09a1797dcc8fbafd198665fb665ede93f009))
+
+
+### Bug Fixes
+
+* close streaming HTTP connections when consumer raises ([#235](https://github.com/janeapp/riffer/issues/235)) ([2a51a10](https://github.com/janeapp/riffer/commit/2a51a106d0f9d1410040c6b3a887722378a0dc14))
+
+## [0.26.0](https://github.com/janeapp/riffer/compare/riffer/v0.25.0...riffer/v0.26.0) (2026-04-29)
+
+
+### Features
+
+* model-aware skills adapter selection ([#232](https://github.com/janeapp/riffer/issues/232)) ([74a5323](https://github.com/janeapp/riffer/commit/74a5323945f3f6f30538d472400cc5fe27b588da))
+
 ## [0.25.0](https://github.com/janeapp/riffer/compare/riffer/v0.24.2...riffer/v0.25.0) (2026-04-29)
 
 

data/README.md

@@ -60,6 +60,7 @@ For comprehensive documentation, see the [docs](docs/) directory:
 - [Evals](docs/11_EVALS.md) - Evaluating agent quality
 - [Guardrails](docs/12_GUARDRAILS.md) - Input/output validation
 - [Skills](docs/13_SKILLS.md) - Packaged agent capabilities
+- [MCP](docs/14_MCP.md) - Integrating third-party MCP servers
 - [Providers](docs/providers/01_PROVIDERS.md) - LLM provider adapters
 
 ### API Reference

data/docs/03_AGENTS.md

@@ -124,6 +124,10 @@ class MyAgent < Riffer::Agent
 end
 ```
 
+### use_mcp
+
+Loads tools from registered [MCP](14_MCP.md) servers by tag. Like `uses_tools`, **`use_mcp` is not inherited**—add it on each subclass that should include MCP tools.
+
 ### provider_options
 
 Passes options to the provider client:

data/docs/10_CONFIGURATION.md

@@ -34,6 +34,25 @@ Riffer.config.anthropic.api_key
 
 For provider credentials and setup, see the individual [Provider guides](providers/).
 
+### MCP (Model Context Protocol)
+
+Optional settings for [MCP server integrations](14_MCP.md):
+
+| Option             | Description                                                                                                     |
+| ------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `credentials`      | Optional `Proc` for per-run `tools/call` HTTP headers: `->(manifest:, matched_tags:, context:) { Hash or nil }` |
+| `discovery_runner` | `Riffer::Runner` instance for tool discovery (default `Runner::Sequential.new`)                                 |
+
+```ruby
+Riffer.configure do |config|
+  config.mcp.credentials = lambda do |manifest:, matched_tags:, context:|
+    {"Authorization" => "Bearer #{token_for(context)}"}
+  end
+end
+```
+
+See [MCP](14_MCP.md) for registration, tags, and agent `use_mcp`.
+
 ### Tool Runtime (Experimental)
 
 > **Warning:** This feature is experimental and may be removed or changed without warning in a future release.
@@ -46,11 +65,11 @@ Riffer.configure do |config|
 end
 ```
 
-| Value                          | Description                                                                                       |
-| ------------------------------ | ------------------------------------------------------------------------------------------------- |
-| `Riffer::ToolRuntime` subclass | Instantiated automatically (e.g., `Riffer::ToolRuntime::Inline`, `Riffer::ToolRuntime::Threaded`) |
-| `Riffer::ToolRuntime` instance | Custom runtime with specific options                                                              |
-| `Proc`                         | Dynamic resolution                                                                                |
+| Value                           | Description                                                                                        |
+| ------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `Riffer::ToolRuntime` subclass  | Instantiated automatically (e.g., `Riffer::ToolRuntime::Inline`, `Riffer::ToolRuntime::Threaded`)  |
+| `Riffer::ToolRuntime` instance  | Custom runtime with specific options                                                               |
+| `Proc`                          | Dynamic resolution                                                                                 |
 
 Per-agent configuration overrides this global default. See [Advanced Tool Configuration — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
 

data/docs/13_SKILLS.md

@@ -70,7 +70,7 @@ end
 
 ### Custom Adapter
 
-The adapter controls how the skill catalog is rendered in the system prompt and which tool the LLM calls to activate a skill. The adapter is auto-selected by provider (Markdown for most, XML for Anthropic). Override with:
+The adapter controls how the skill catalog is rendered in the system prompt and which tool the LLM calls to activate a skill. The adapter is auto-selected by provider, with model-aware fallback for proxy providers — Markdown for most providers, XML for Anthropic, and XML for Anthropic models routed through Amazon Bedrock (e.g. `us.anthropic.claude-sonnet-4-6`). Override with:
 
 ```ruby
 skills do

data/docs/14_MCP.md

@@ -0,0 +1,144 @@
+# MCP
+
+Riffer can consume third-party [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers as tool sources. Tools are discovered automatically at registration time — no handwritten Ruby per tool required.
+
+## Overview
+
+1. Register an MCP server globally with `Riffer::Mcp.register`.
+2. Opt an agent into that server's tools using the `use_mcp` DSL.
+3. The agent picks up the tools and calls them like any other Riffer tool.
+
+## Registering a Server
+
+```ruby
+Riffer::Mcp.register(
+  name: "github",        # unique identifier
+  tags: [:github],       # agents opt-in by tag
+  endpoint: "https://mcp.github.com",
+  discovery_headers: -> { {"Authorization" => "Bearer #{ENV['GITHUB_TOKEN']}"} }
+)
+```
+
+`register` blocks until tool discovery completes (or fails). Discovery uses the configured `Riffer::Runner` (default `Runner::Sequential` — inline). To run discovery on a pool thread (e.g. for Rails connection-pool isolation), set `config.mcp.discovery_runner = Riffer::Runner::Threaded.new`; `register` still blocks but the work runs off the calling thread.
+
+### Discovery headers
+
+`discovery_headers` is a Hash or Proc used **only** for MCP `tools/list` when the discovery client is built (the Proc runs once at that time). Use it for bootstrap identity: service account, env-based token, or `{}` if listing is unauthenticated.
+
+Optional **`credentials_scope`** on the manifest documents whether you expect invocation headers to depend on tenant and/or user keys in the agent `context` (e.g. `:global`, `:tenant`, `:user`). It does **not** store tenant or user ids — only a hint for your app and docs. For multi-tenant apps, `:user` often means “user in tenant” and your `context` may include both tenant and user identifiers.
+
+## Session credentials callback
+
+When **`Riffer.config.mcp.credentials`** is set to a Proc, each MCP `tools/call` resolves HTTP headers through that callback instead of reusing `discovery_headers`.
+
+**Signature:**
+
+```ruby
+Riffer.configure do |config|
+  config.mcp.credentials = lambda do |manifest:, matched_tags:, context:|
+    # return nil to omit this server's tools for this agent run (at resolve time)
+    # return Hash<String,String> headers for tools/call (e.g. Authorization)
+  end
+end
+```
+
+- **`manifest`** — the server's `Riffer::Mcp::Manifest`.
+- **`matched_tags`** — intersection of the agent's `use_mcp` tags and `manifest.tags` for this registration (unioned across multiple `use_mcp` lines).
+- **`context`** — the same hash passed to `generate` / `stream` for this run.
+
+**Resolve time:** Before tools are exposed to the model, the proc is invoked once per matching registration. If it returns **`nil`**, that server's tools are omitted for this run (e.g. tenant has no integration).
+
+**Call time:** Authenticated tool wrappers invoke the proc again for each execution. If it returns **`nil`**, `Riffer::Mcp::CredentialsDeniedError` is raised.
+
+If **`credentials` is unset**, discovery and `tools/call` share one client built from `discovery_headers` (same behaviour as a single static token for both list and call).
+
+## Tags
+
+Tags are entirely up to your application; Riffer does not define a canonical vocabulary. Each server may declare multiple tags; an agent includes every registration that shares **any** tag passed to `use_mcp`.
+
+When MCPs are registered, assign **stable bucket tags** so agent classes can opt in without listing every server name—for example `tags: [:connectors, :github]` with `use_mcp :connectors` for all enabled connectors, or `use_mcp :github` for that integration only.
+
+Registrations are **global** (endpoint + tags); **tenant and user** access are enforced in your **`credentials`** proc and whatever you put in **`context`**, not by putting ids on the manifest.
+
+## Opting an Agent In
+
+```ruby
+class ResearchAgent < Riffer::Agent
+  model "openai/gpt-5-mini"
+  instructions "You are a research assistant."
+
+  use_mcp :github
+end
+```
+
+`use_mcp` accepts any tag registered via `Riffer::Mcp.register`. Multiple calls accumulate — the agent receives tools from all matching servers:
+
+```ruby
+class MultiAgent < Riffer::Agent
+  model "openai/gpt-5-mini"
+
+  use_mcp :github
+  use_mcp :jira
+end
+```
+
+MCP tools are appended after any tools declared with `uses_tools`.
+
+Tool names must be unique across `uses_tools` and all included MCP servers; duplicate names raise `Riffer::ArgumentError` when tools are resolved.
+
+### Subclassing
+
+Like [`uses_tools`](03_AGENTS.md#uses_tools), **`use_mcp` is not inherited** from the superclass. Declare `use_mcp` on each agent class that should load MCP tools.
+
+## Unregistering a Server
+
+```ruby
+Riffer::Mcp.unregister("github")
+```
+
+Subsequent agent runs will not include tools from that server. Call `register` again (with fresh `discovery_headers` if needed) to re-register.
+
+## Introspection
+
+```ruby
+Riffer::Mcp.registrations
+# => {"github" => #<Riffer::Mcp::Registration ...>, ...}
+
+reg = Riffer::Mcp.registrations["github"]
+reg.tools    # => [<Class:...>, ...]  (Riffer::Tool subclasses)
+```
+
+Discovery failures raise from `register` directly, typically `Faraday::Error` for network issues or `Riffer::DependencyError` if the `mcp`/`faraday` gems are missing. Rescue `StandardError` for graceful degradation:
+
+```ruby
+begin
+  Riffer::Mcp.register(name: "github", ...)
+rescue StandardError => e
+  Rails.logger.warn("MCP registration failed: #{e.message}")
+end
+```
+
+## Error Classes
+
+| Class                                 | Raised when                                          |
+| ------------------------------------- | ---------------------------------------------------- |
+| `Riffer::Mcp::CredentialsDeniedError` | `credentials` proc returns `nil` during `tools/call` |
+
+All inherit from `Riffer::Mcp::Error < Riffer::Error`.
+
+## Limitations
+
+- **Tool results:** `tools/call` responses are reduced to joined **text** content from MCP `content` items. Non-text parts (e.g. images, embedded resources) are not surfaced in this release.
+- **Session credentials:** When `Riffer.config.mcp.credentials` is set, authenticated tool wrappers may build a **new HTTP client per tool invocation** so headers stay fresh; there is no connection pooling in this release.
+- **Context window / progressive disclosure:** Discovery registers **all** tools from each server; matching agents see the full set in one shot. There is no built-in lazy listing or prompt-size budgeting yet. Tighter control may require application-level filtering, MCP server design, or future Riffer APIs.
+
+## Requirements
+
+The `mcp` and `faraday` gems are **optional** dependencies — they are not included in Riffer's runtime gemspec. To use MCP integration, add both to your own Gemfile:
+
+```ruby
+gem "mcp"
+gem "faraday"
+```
+
+Faraday is required for the MCP HTTP transport. If either gem is missing when `Riffer::Mcp.register` is called, a `Riffer::DependencyError` is raised.

data/lib/riffer/agent.rb

@@ -172,6 +172,24 @@ class Riffer::Agent
   end
   private_class_method :resolve_uses_tools_config
 
+  # Opts this agent into tools from all MCP registrations that share any of
+  # the given tag(s).
+  #
+  # +tag+ - a String or Symbol; matched against registration manifest tags.
+  #
+  #: (String | Symbol) -> void
+  def self.use_mcp(tag)
+    @mcp_configs ||= []
+    @mcp_configs << {tags: [tag.to_sym]}
+  end
+
+  # Returns the accumulated +use_mcp+ configurations for this agent class.
+  #
+  #: () -> Array[Hash[Symbol, untyped]]
+  def self.mcp_configs
+    @mcp_configs || []
+  end
+
   # Gets or sets the tool runtime for this agent.
   #
   # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,
@@ -755,9 +773,70 @@ class Riffer::Agent
   end
 
   #--
+  #: () -> Array[singleton(Riffer::Tool)]
+  def resolve_uses_tools_config
+    config = self.class.uses_tools
+
+    if config.nil?
+      []
+    elsif config.is_a?(Proc)
+      (config.arity == 0) ? config.call : config.call(@context)
+    else
+      config
+    end
+  end
+
+  #--
+  #: () -> Array[singleton(Riffer::Tool)]
+  def resolve_mcp_tool_classes
+    configs = self.class.mcp_configs
+    return [] if configs.empty?
+
+    cred = Riffer.config.mcp.credentials
+    ctx = @context
+    gather_mcp_registrations_with_tags(configs).flat_map do |reg, tag_accum|
+      matched_tags = tag_accum.uniq
+      mcp_tools_for_registration(reg, matched_tags, cred, ctx)
+    end
+  end
+
+  # Each matching MCP registration once, with tag symbols unioned across +use_mcp+ rows.
+  #
+  #: (Array[Hash[Symbol, untyped]]) -> Hash[Riffer::Mcp::Registration, Array[Symbol]]
+  def gather_mcp_registrations_with_tags(configs)
+    by_reg = {}
+    configs.each do |cfg|
+      Riffer::Mcp::Registry.find_by_tags(cfg[:tags]).each do |reg|
+        (by_reg[reg] ||= []).concat(cfg[:tags] & reg.manifest.tags)
+      end
+    end
+    by_reg
+  end
+
+  #: (Riffer::Mcp::Registration, Array[Symbol], Proc?, Hash[Symbol, untyped]) -> Array[singleton(Riffer::Tool)]
+  def mcp_tools_for_registration(reg, matched_tags, cred, ctx)
+    return reg.tools unless cred
+    return [] if cred.call(manifest: reg.manifest, matched_tags: matched_tags, context: ctx).nil?
+    Riffer::Mcp::AuthenticatedTool.wrap_all(reg.tools, reg.manifest, matched_tags)
+  end
+
+  # Raises if two or more tool classes share the same +.name+ (ambiguous dispatch).
+  #
+  #: (Array[singleton(Riffer::Tool)]) -> void
+  def assert_distinct_tool_names!(tool_classes)
+    tally = Hash.new(0) #: Hash[String, Integer]
+    tool_classes.each { |tc| tally[tc.name] += 1 }
+    dupes = tally.filter_map { |name, n| name if n > 1 }
+    return if dupes.empty?
+
+    raise Riffer::ArgumentError, "Duplicate tool names: #{dupes.sort.join(", ")}"
+  end
+
   #: () -> Array[singleton(Riffer::Tool)]
   def resolved_tools
-    @resolved_tools ||= self.class.resolved_tool_classes(context: @context)
+    @resolved_tools ||= self.class.resolved_tool_classes(context: @context) + resolve_mcp_tool_classes
+    assert_distinct_tool_names!(@resolved_tools)
+    @resolved_tools
   end
 
   #--
@@ -799,7 +878,7 @@ class Riffer::Agent
     return nil if skills_list.empty?
 
     skills = skills_list.to_h { |s| [s.name, s] }
-    adapter_class = self.class.skills.adapter || provider_class.skills_adapter
+    adapter_class = self.class.skills.adapter || provider_class.skills_adapter(@model_name)
     skill_activate_tool_class = self.class.skills.activate_tool || Riffer.config.skills.default_activate_tool
 
     skills_context = Riffer::Skills::Context.new(

data/lib/riffer/config.rb

@@ -21,6 +21,7 @@ class Riffer::Config
   Gemini = Struct.new(:api_key, :open_timeout, :read_timeout, keyword_init: true)
   OpenAI = Struct.new(:api_key, keyword_init: true)
   Evals = Struct.new(:judge_model, keyword_init: true)
+  Mcp = Struct.new(:credentials, :discovery_runner, keyword_init: true)
 
   # Skills-related global configuration.
   #
@@ -93,6 +94,17 @@ class Riffer::Config
   # Evals configuration (Struct with +judge_model+).
   attr_reader :evals #: Riffer::Config::Evals
 
+  # MCP configuration (Struct with +credentials+ and +discovery_runner+).
+  #
+  # +credentials+ is an optional Proc for per-run MCP +tools/call+ HTTP headers.
+  # Signature: +->(manifest:, matched_tags:, context:) { Hash or nil }+.
+  # +nil+ from the proc at tool-resolution time omits that server's tools; +nil+
+  # at tool-call time raises Riffer::Mcp::CredentialsDeniedError.
+  #
+  # +discovery_runner+ is the Riffer::Runner used to execute tool discovery
+  # (default +Runner::Sequential+).
+  attr_reader :mcp #: Riffer::Config::Mcp
+
   # Global tool runtime configuration (experimental).
   #
   # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,
@@ -148,6 +160,7 @@ class Riffer::Config
     @gemini = Gemini.new
     @openai = OpenAI.new
     @evals = Evals.new
+    @mcp = Mcp.new(credentials: nil, discovery_runner: Riffer::Runner::Sequential.new)
     @tool_runtime = Riffer::ToolRuntime::Inline.new
     @skills = Skills.new
     @message_id_strategy = :none

data/lib/riffer/mcp/authenticated_tool.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Wraps MCP-generated tool classes so +tools/call+ uses +Riffer.config.mcp.credentials+
+# per invocation while delegating metadata to the inner class.
+#
+module Riffer::Mcp::AuthenticatedTool
+  # Returns one wrapper class per inner tool, sharing +manifest+ and +matched_tags+.
+  #
+  #--
+  #: (Array[singleton(Riffer::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Tool)]
+  def self.wrap_all(tool_classes, manifest, matched_tags)
+    tool_classes.map { |tc| wrap_one(tc, manifest, matched_tags) }
+  end
+
+  #--
+  #: (singleton(Riffer::Tool), Riffer::Mcp::Manifest, Array[Symbol]) -> singleton(Riffer::Tool)
+  # Class.new(Riffer::Tool) is typed as ::Class by steep — it cannot verify the subtype
+  # relationship for dynamically created anonymous classes, so the ignore is required.
+  def self.wrap_one(inner_class, manifest, matched_tags) # steep:ignore MethodBodyTypeMismatch
+    inner = inner_class
+    man = manifest
+    tags = matched_tags
+
+    Class.new(Riffer::Tool) do
+      @identifier = inner.identifier
+
+      define_singleton_method(:name) { inner.name }
+      define_singleton_method(:mcp_server_tool_name) { inner.mcp_server_tool_name }
+      define_singleton_method(:description) { inner.description }
+      define_singleton_method(:parameters_schema) { |strict: false| inner.parameters_schema(strict: strict) }
+
+      # Builds a client for a single +tools/call+ invocation.
+      #
+      # Creates a fresh client per call so headers from the credentials proc stay
+      # current.
+      # TODO: A per-headers cache would reduce connection churn under load, and
+      # requires a follow-up investigation to determine how to invalidate failing
+      # clients.
+      define_method(:build_call_client) do |endpoint, headers|
+        Riffer::Mcp::Client.new(endpoint: endpoint, headers: headers)
+      end
+      private :build_call_client
+
+      define_method(:call) do |context:, **kwargs|
+        cred = Riffer.config.mcp.credentials
+        unless cred
+          # `next` rather than `return`: inside define_method the block IS the method
+          # body, so both exit :call identically at runtime. `next` avoids a false
+          # steep ReturnTypeMismatch that would otherwise need a steep:ignore.
+          next inner.new.call(context: context, **kwargs)
+        end
+
+        headers = cred.call(manifest: man, matched_tags: tags, context: context)
+        if headers.nil?
+          raise Riffer::Mcp::CredentialsDeniedError,
+            "MCP credentials returned nil for server '#{man.name}' during tools/call"
+        end
+
+        client = build_call_client(man.endpoint, headers)
+        text(client.tools_call(inner.mcp_server_tool_name, kwargs))
+      end
+    end
+  end
+end

data/lib/riffer/mcp/client.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Thin wrapper around the MCP Ruby SDK client (mcp gem v0.8+).
+#
+# Resolves headers (if a Proc) once at initialization, then provides
+# +tools_list+ and +tools_call+. Used for discovery (+Manifest#discovery_headers+)
+# and for +tools/call+ when no +credentials+ proc is configured.
+#
+# MCP gem API used:
+#   MCP::Client::HTTP.new(url:, headers:)  — HTTP transport (requires faraday)
+#   MCP::Client.new(transport:)            — client
+#   client.tools                           — Array<MCP::Client::Tool>
+#   client.call_tool(tool:, arguments:)    — raw JSON-RPC response Hash
+#
+class Riffer::Mcp::Client
+  include Riffer::Helpers::Dependencies
+
+  #--
+  #: (endpoint: String, ?headers: (Hash[String, String] | Proc), ?client: untyped?) -> void
+  def initialize(endpoint:, headers: {}, client: nil)
+    depends_on "mcp"
+    depends_on "faraday"
+
+    @client = client || begin
+      resolved_headers = headers.is_a?(Proc) ? headers.call : headers
+      transport = MCP::Client::HTTP.new(url: endpoint, headers: resolved_headers)
+      MCP::Client.new(transport: transport)
+    end
+  end
+
+  # Returns an array of tool definition hashes, each with +:name+, +:description+,
+  # and +:input_schema+ keys.
+  #
+  #--
+  #: () -> Array[Hash[Symbol, untyped]]
+  def tools_list
+    @client.tools.map do |tool|
+      {
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.input_schema
+      }
+    end
+  end
+
+  # Calls a tool on the MCP server and returns joined text content from the response.
+  #
+  #--
+  #: (String, ?Hash[untyped, untyped]) -> String
+  def tools_call(name, arguments = {})
+    tool = MCP::Client::Tool.new(name: name, description: nil, input_schema: nil)
+    response = @client.call_tool(tool: tool, arguments: arguments)
+
+    if response["error"]
+      raise Riffer::Error, response.dig("error", "message") || "MCP tool call failed"
+    end
+
+    if response.dig("result", "isError")
+      message = (response.dig("result", "content") || []).filter_map { |item| item["text"] }.join
+      raise Riffer::Error, message.empty? ? "MCP tool '#{name}' failed" : message
+    end
+
+    content = response.dig("result", "content") || []
+    content.filter_map { |item| item["text"] }.join
+  end
+end

data/lib/riffer/mcp/manifest.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "uri"
+
+# Riffer::Mcp::Manifest holds the configuration for a single MCP server.
+#
+# +name+                - String identifier used as the registration key and generated-agent identifier.
+# +tags+                - Array[Symbol]; normalized to symbols at construction time.
+# +endpoint+            - String HTTPS URL passed to the MCP transport.
+# +discovery_headers+   - Hash or Proc; resolved once when building the discovery client for +tools/list+.
+# +credentials_scope+  - Optional symbol hint: +:global+, +:tenant+, +:user+ — documents whether
+#   invocation credentials are expected to depend on tenant and/or user keys in +context+ (no ids stored).
+#   Apps may treat +:user+ as "user in tenant" and pass both keys in +context+.
+#
+class Riffer::Mcp::Manifest
+  attr_reader :name #: String
+  attr_reader :tags #: Array[Symbol]
+  attr_reader :endpoint #: String
+  attr_reader :discovery_headers #: (Hash[String, untyped] | ::Proc)?
+  attr_reader :credentials_scope #: Symbol?
+
+  #--
+  #: (name: String, endpoint: String, ?tags: Array[untyped]?, ?discovery_headers: (Hash[String, untyped] | ::Proc)?, ?credentials_scope: (String | Symbol)?) -> void
+  def initialize(name:, endpoint:, tags: nil, discovery_headers: nil, credentials_scope: nil)
+    @name = name.to_s.strip
+    raise Riffer::ArgumentError, "MCP manifest name is required" if @name.empty?
+
+    @endpoint = endpoint.to_s.strip
+    raise Riffer::ArgumentError, "MCP manifest endpoint must be a valid HTTPS URL" unless valid_endpoint?
+
+    @tags = Array(tags).map(&:to_sym)
+    @discovery_headers = discovery_headers
+    @credentials_scope = credentials_scope&.to_sym
+  end
+
+  private
+
+  def valid_endpoint?
+    uri = URI.parse(@endpoint)
+    uri.is_a?(URI::HTTPS) && uri.host
+  rescue URI::InvalidURIError
+    false
+  end
+end