omni_agent 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea0324a20bc12e064b994b4fcdf7af700cd0280ba7b0609dc75724717e9fc881
-  data.tar.gz: dfda03e711340e59dfbb1cd803bc785a51bbe39d972992c6a26fb5b2d4d8761a
+  metadata.gz: f8a84d4b38e835bc00b73a88bc233932198498112e3837e33fdfdf3dbabab981
+  data.tar.gz: 6d5cd7709dc61be01ae892a67732b08ee3e17a6d4af7d81f8640f0fd618010e8
 SHA512:
-  metadata.gz: 72739c339838d0f38c172455226ff79244ab7e739920ec9e7b89f16182d220a1526886bff1f85b7b943bc6426676d5cc4dbd727f903c612df401587fc627f3f0
-  data.tar.gz: b90d265c701efaf90d5d5f5e5f9aac3b337095e998d413bf5e872e05d794a9793a44e0bd669425d30ee13eabd50ded2f0fdc2c19cadbc1ff976ec02d0e8d888f
+  metadata.gz: b56c77174212b7a4ba2e45b2b3bb6e0f384631fcdd2bcbf30e2a32c8edb1617b239e8bdd482dbb259baf48746b20c38d29fd325685262337e38ab1e9669a5220
+  data.tar.gz: 5fcb5179527eda96d3dc6726ad78c73b1bba4b3ef7c34825cbfec03c2437e7018647b43cf9f9d43791599efdc628530d5c6cfefcb6f431bd7548a97f7c9a8365

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.10](https://github.com/ACR1209/omni_agent/compare/omni_agent/v0.1.9...omni_agent/v0.1.10) (2026-10-09)
+
+
+### Features
+
+* **mcp:** expose tools and agents as MCP servers ([#40](https://github.com/ACR1209/omni_agent/issues/40)) ([db8dcb8](https://github.com/ACR1209/omni_agent/commit/db8dcb8776cc0baaed45112b61bc329f03d32181))
+
+## [0.1.9](https://github.com/ACR1209/omni_agent/compare/omni_agent/v0.1.8...omni_agent/v0.1.9) (2026-07-12)
+
+
+### Features
+
+* **agent:** support streaming responses via stream sink ([7cf1fba](https://github.com/ACR1209/omni_agent/commit/7cf1fba4fa378c5cee7f464354f760506a0ff513))
+* **docs:** add enum type for temperature unit in input schema ([d992658](https://github.com/ACR1209/omni_agent/commit/d99265836307ce8f863b060eff73c7acdbc8d2ff))
+* **providers:** add Ollama provider via OpenAI-compat endpoint ([4ae92ad](https://github.com/ACR1209/omni_agent/commit/4ae92ad0f549119b43c2e8a7381f4f7245aa2f68))
+* **tool:** add optional constraint validations and custom validate procs ([db8371a](https://github.com/ACR1209/omni_agent/commit/db8371a189f710e812c3c3ce15f200df1ba94902))
+* **tool:** add polymorphic reference datatype ([1686bbb](https://github.com/ACR1209/omni_agent/commit/1686bbbf41932622a5537c335da8c41c68a73f73))
+* **tool:** infer and validate enum value types in schema builder ([ceb3e78](https://github.com/ACR1209/omni_agent/commit/ceb3e780498caa1158e9fc8af3eb6e9b95c33ddb))
+* **tool:** validate required and enum arguments on invoke ([543c6e0](https://github.com/ACR1209/omni_agent/commit/543c6e08f9c394b84c73bc5957aff7058e0fab19))
+
+
+### Bug Fixes
+
+* **lint:** add space inside empty block braces ([9116b3f](https://github.com/ACR1209/omni_agent/commit/9116b3ff82e9fab9824347515b4c1cd40a40785e))
+* **spec:** redact OpenAI API key from recorded VCR cassettes ([53cecd5](https://github.com/ACR1209/omni_agent/commit/53cecd540b6dd52ddc5bf3da0550836fbfcfab88))
+
 ## [0.1.8](https://github.com/ACR1209/omni_agent/compare/omni_agent/v0.1.7...omni_agent/v0.1.8) (2026-07-07)
 
 

data/README.md

@@ -11,7 +11,8 @@ tool schemas, and generation lifecycle callbacks.
 - Prompt composition from ERB files in `app/agents/<agent_name>/`
 - Agent callbacks (`before_generation`, `after_generation`)
 - Agent and tool tags to support filtering strategies
-- OpenAI provider integration out of the box
+- OpenAI provider integration out of the box, plus an Ollama provider for local models
+- MCP server support: expose tools and whole agents to Claude Code, Claude Desktop, Cursor and other MCP clients
 - Rake tasks and Rails generators for scaffolding
 
 ## Installation
@@ -27,6 +28,8 @@ Add the provider you're using to the Gemfile as well:
 gem "openai"
 ```
 
+The `ollama` provider also depends on the `openai` gem — it talks to Ollama's OpenAI-compatible endpoint, so no separate gem is needed.
+
 Then run:
 
 ```bash
@@ -53,6 +56,14 @@ bundle exec rails generate omni_agent:agent ResearchAgent --model gpt-4.1-mini -
 OPENAI_ACCESS_TOKEN=your_api_key_here
 ```
 
+To use Ollama instead, set `config.default_provider = :ollama` (see below) and, if needed, override its endpoint/model:
+
+```dotenv
+OLLAMA_HOST=http://localhost:11434   # defaults to this
+OLLAMA_MODEL=llama3.1                # defaults to this; pick a tool-calling-capable model
+OLLAMA_API_KEY=ollama                # unused by Ollama, but required by the openai client
+```
+
 4. Implement your agent prompt and optional tools under:
 
 ```text
@@ -129,6 +140,23 @@ class SupervisorAgent < OmniAgent::Agent
 end
 ```
 
+## Streaming
+
+Prefix any run entrypoint with `.stream` and pass a block to receive the response as it's generated instead of waiting for the full result:
+
+```ruby
+ResearchAgent.with(user_id: 42).stream.run("What's new?") do |event|
+	case event.type
+	when :text        then print event.text
+	when :tool_call   then puts "\n[using #{event.tool_name}...]"
+	when :tool_result then puts "[#{event.error? ? "failed" : "done"}]"
+	when :done        then puts "\n---"
+	end
+end
+```
+
+`.stream` must come before the call (`.stream.run(...)`, not `.run(...).stream`) — without it, or without a block, behavior is unchanged and the same `Response` is returned either way. Only the `openai`, `ollama`, and `mock` providers stream today. See [Streaming Responses](omniagent-docs/docs/agent/streaming.mdx) for the full event reference.
+
 ## Evals
 
 `OmniAgent::Eval` lets you test agent quality: deterministic assertions (tool calls, output matching) and pluggable LLM-as-judge scoring.
@@ -213,6 +241,51 @@ There's also an equivalent `rake omni_agent:eval` task (`rake "omni_agent:eval[p
 
 Calls real LLM providers (cost, non-determinism) — deliberately **not** part of `bundle exec rspec` or CI.
 
+## MCP Servers
+
+Expose your tools (and whole agents) to MCP clients such as Claude Code, Claude Desktop and Cursor. The protocol is implemented natively; no extra gem is needed.
+
+```bash
+rails generate omni_agent:mcp_server Support --with-tools LookupOrder --agents SupportAgent
+```
+
+```ruby
+# app/mcp_servers/support_server.rb
+class SupportServer < OmniAgent::MCP::Server
+	instructions "Tools for the support team."
+
+	# Tools in app/mcp_servers/support_server/tools/ (SupportServer::Tools::*) are added automatically.
+	# Reuse existing tools and agents too:
+	tools ResearchAgent::Tools::GetWeather
+	tools_from SupportAgent
+	expose_agent ResearchAgent, as: :research, description: "Ask the research agent", forward: [ :current_user ]
+
+	authenticate :bearer, tokens: -> { ENV.fetch("SUPPORT_MCP_TOKENS", "").split(",") }
+	# or: authenticate { |request| User.find_by(api_token: request.bearer_token) }
+
+	authorize_tool { |tool_class, principal| !tool_class.tags.include?(:admin) }
+	context { |principal, _request| { current_user: principal } }
+end
+```
+
+```ruby
+# config/routes.rb -- Streamable HTTP (stateless, POST only)
+mcp_server :support                        # SupportServer at /mcp/support
+mcp_server :billing, path: "/internal/mcp"
+# or mount every server in app/mcp_servers at /mcp/<name>:
+mcp_servers
+```
+
+```bash
+# stdio, for local clients
+bundle exec omni_agent mcp SupportServer
+
+claude mcp add --transport http support http://localhost:3000/mcp/support --header "Authorization: Bearer $TOKEN"
+claude mcp add support -- bundle exec omni_agent mcp SupportServer
+```
+
+Tools can declare MCP-only hints with `title "Get weather"` and `annotations read_only: true, destructive: false, idempotent: true, open_world: true`. HTTP servers must declare `authenticate` (use `authenticate :none` to opt out on purpose). Requests from browser origins that are not in `allowed_origins` / `config.mcp_allowed_origins` are rejected.
+
 ## Configuration
 
 Global defaults can be configured through `OmniAgent.configure`:

data/exe/omni_agent

@@ -5,10 +5,21 @@ require "optparse"
 
 options = { fresh: false }
 parser = OptionParser.new do |opts|
-  opts.banner = "Usage: omni_agent eval [pattern] [options]"
+  opts.banner = <<~BANNER
+    Usage: omni_agent eval [pattern] [options]
+           omni_agent mcp <ServerClass>
+  BANNER
   opts.on("--fresh", "Clear the eval cache before running") { options[:fresh] = true }
 end
 
+def require_rails_environment(command)
+  environment_file = File.expand_path("config/environment", Dir.pwd)
+  unless File.exist?("#{environment_file}.rb")
+    abort "Could not find config/environment.rb -- run `omni_agent #{command}` from your Rails app root."
+  end
+  require environment_file
+end
+
 command = ARGV.shift
 
 case command
@@ -16,11 +27,7 @@ when "eval"
   parser.parse!(ARGV)
   pattern = ARGV.shift
 
-  environment_file = File.expand_path("config/environment", Dir.pwd)
-  unless File.exist?("#{environment_file}.rb")
-    abort "Could not find config/environment.rb -- run `omni_agent eval` from your Rails app root."
-  end
-  require environment_file
+  require_rails_environment("eval")
 
   status = OmniAgent::Eval::CLI.run(pattern: pattern, fresh: options[:fresh])
 
@@ -32,6 +39,15 @@ when "eval"
   when :failed
     exit 1
   end
+when "mcp"
+  server = ARGV.shift.to_s.strip
+  if server.empty?
+    warn "Missing server class. Example: omni_agent mcp SupportServer"
+    exit 1
+  end
+
+  require_rails_environment("mcp")
+  OmniAgent::MCP::Stdio.start(server)
 when nil
   warn parser.banner
   exit 1

data/lib/generators/omni_agent/agent/agent_generator.rb

@@ -7,6 +7,7 @@ module OmniAgent
       class_option :with_tools,
                    type: :array,
                    default: nil,
+                   lazy_default: [],
                    banner: "[Tool1 Tool2 ...]",
                    desc: "Create tools folder and scaffold tools. Optionally pass tool names"
       class_option :model,

data/lib/generators/omni_agent/install/install_generator.rb

@@ -15,6 +15,7 @@ module OmniAgent
       def show_next_steps
         say "OmniAgent install complete."
         say "Next: rails generate omni_agent:agent SupportAgent --with-tools Tool1 Tool2"
+        say "Expose tools to MCP clients: rails generate omni_agent:mcp_server Support --agents SupportAgent"
       end
     end
   end

data/lib/generators/omni_agent/mcp_server/mcp_server_generator.rb

@@ -0,0 +1,151 @@
+require "rails/generators/named_base"
+
+module OmniAgent
+  module Generators
+    class McpServerGenerator < Rails::Generators::NamedBase
+      desc "Creates an OmniAgent MCP server in app/mcp_servers and mounts it in config/routes.rb"
+
+      class_option :with_tools,
+                   type: :array,
+                   default: nil,
+                   lazy_default: [],
+                   banner: "[Tool1 Tool2 ...]",
+                   desc: "Scaffold server-local tools in app/mcp_servers/<name>_server/tools. Optionally pass tool names"
+      class_option :tools,
+                   type: :array,
+                   default: [],
+                   banner: "[ResearchAgent::Tools::GetWeather ...]",
+                   desc: "Existing tool classes to expose"
+      class_option :agents,
+                   type: :array,
+                   default: [],
+                   banner: "[ResearchAgent ...]",
+                   desc: "Agents whose tools are all exposed (tools_from)"
+      class_option :path,
+                   type: :string,
+                   default: nil,
+                   desc: "Mount path for the HTTP endpoint (default: /mcp/<name>)"
+
+      def create_server_file
+        create_file(File.join("app", "mcp_servers", "#{server_file_name}.rb"), server_template)
+      end
+
+      def create_tools_if_requested
+        return if options[:with_tools].nil?
+
+        requested_tool_names.each do |tool_name|
+          create_file(File.join("app", "mcp_servers", server_file_name, "tools", "#{tool_name.underscore}.rb"), tool_template(tool_name))
+        end
+      end
+
+      def mount_route
+        if mounts_all_servers?
+          say_status :skip, "config/routes.rb already mounts every server with `mcp_servers`", :yellow
+          return
+        end
+
+        route_line = "mcp_server #{server_slug.include?('/') ? server_slug.inspect : ":#{server_slug}"}"
+        route_line += %(, path: "#{options[:path]}") if options[:path].present?
+        route route_line
+      end
+
+      def show_next_steps
+        say ""
+        say "MCP server #{server_class_name} created."
+        say ""
+        say "Set a token, start the app and connect Claude Code over HTTP:"
+        say "  #{token_env_var}=change-me bin/rails server"
+        say "  claude mcp add --transport http #{server_identifier} http://localhost:3000#{mount_path} --header \"Authorization: Bearer change-me\""
+        say ""
+        say "Or run it locally over stdio (no HTTP auth; see stdio_principal):"
+        say "  claude mcp add #{server_identifier} -- bundle exec omni_agent mcp #{server_class_name}"
+      end
+
+      private
+
+      def server_class_name
+        class_name.end_with?("Server") ? class_name : "#{class_name}Server"
+      end
+
+      def server_file_name
+        server_class_name.underscore
+      end
+
+      def server_slug
+        OmniAgent::MCP::Routing.slug_for(server_class_name)
+      end
+
+      def server_identifier
+        server_slug.tr("/", "_")
+      end
+
+      def mount_path
+        options[:path].presence || "#{OmniAgent::MCP::Routing::DEFAULT_PATH_PREFIX}/#{server_slug.dasherize}"
+      end
+
+      def mounts_all_servers?
+        routes_file = File.join(destination_root, "config", "routes.rb")
+        File.exist?(routes_file) && File.read(routes_file).match?(/^\s*mcp_servers\s*(\(\s*\)|except:.*)?\s*$/)
+      end
+
+      def token_env_var
+        "#{server_identifier.upcase}_MCP_TOKENS"
+      end
+
+      def server_template
+        <<~RUBY
+          class #{server_class_name} < OmniAgent::MCP::Server
+            instructions "Tools exposed by #{server_class_name}."
+
+          #{tool_lines.map { |line| "  #{line}" }.join("\n")}
+
+            # Comma-separated list of accepted bearer tokens.
+            authenticate :bearer, tokens: -> { ENV.fetch("#{token_env_var}", "").split(",") }
+
+            # Hide tools per principal:
+            # authorize_tool { |tool_class, principal| true }
+
+            # Extra values merged into each tool's `context`:
+            # context { |principal, request| { current_user: principal } }
+          end
+        RUBY
+      end
+
+      def requested_tool_names
+        names = Array(options[:with_tools]).map(&:strip).reject(&:empty?)
+        names.empty? ? [ "ExampleTool" ] : names.map(&:camelize)
+      end
+
+      def tool_template(tool_name)
+        <<~RUBY
+          module #{server_class_name}::Tools
+            class #{tool_name} < OmniAgent::Tool
+              description "#{tool_name} generated by omni_agent:mcp_server"
+              annotations read_only: true
+
+              input do
+                string :input_text, description: "Text input"
+              end
+
+              def execute(input_text:)
+                "Echo: \#{input_text}"
+              end
+            end
+          end
+        RUBY
+      end
+
+      def tool_lines
+        tools = Array(options[:tools]).map(&:strip).reject(&:empty?)
+        agents = Array(options[:agents]).map(&:strip).reject(&:empty?)
+
+        lines = []
+        lines << "tools #{tools.join(', ')}" if tools.any?
+        lines.concat(agents.map { |agent| "tools_from #{agent}" })
+        lines.unshift("# Tools in app/mcp_servers/#{server_file_name}/tools/ are added automatically.")
+        lines << "# tools SomeAgent::Tools::SomeTool" if tools.empty? && agents.empty?
+        lines
+      end
+    end
+  end
+end

data/lib/omni_agent/agent.rb

@@ -20,7 +20,7 @@ module OmniAgent
         @_omni_agent_wrapping_method = true
         alias_method alias_name, method_name
 
-        define_method(method_name) do |input = nil, context: {}, **context_keywords|
+        define_method(method_name) do |input = nil, context: {}, **context_keywords, &block|
           if input.nil? && context == {} && context_keywords.empty?
             run_alias_entrypoint_logic(alias_name)
           else
@@ -29,7 +29,7 @@ module OmniAgent
 
             run_input = run_alias_entrypoint_logic(alias_name, fallback_input: input)
 
-            run(run_input, context: merged_context, prompt_method: method_name)
+            run(run_input, context: merged_context, prompt_method: method_name, &block)
           end
         end
       ensure
@@ -78,8 +78,8 @@ module OmniAgent
         aliases = normalize_callbacks(:run_aliases, method_names)
 
         aliases.each do |method_name|
-          define_method(method_name) do |input, context: {}|
-            run(input, context: context, prompt_method: method_name)
+          define_method(method_name) do |input, context: {}, &block|
+            run(input, context: context, prompt_method: method_name, &block)
           end
         end
       end
@@ -99,6 +99,38 @@ module OmniAgent
         @delegated_tool_classes || []
       end
 
+      def tool_classes
+        tool_namespace = "#{name}::Tools".safe_constantize
+
+        namespace_tools = if tool_namespace
+          tool_namespace.constants.filter_map do |const_name|
+            const = tool_namespace.const_get(const_name)
+            const if const.is_a?(Class) && const < OmniAgent::Tool
+          end
+        else
+          []
+        end
+
+        namespace_tools + configured_delegated_tool_classes
+      end
+
+      def build_delegated_tool_class(agent_class, description:, run_alias:, forward:)
+        tool_description = description || "Delegate to #{agent_class.name}."
+
+        Class.new(OmniAgent::Tool) do
+          description tool_description
+
+          input do
+            string :input, description: "Input/question to send to the delegated agent."
+          end
+
+          define_method(:execute) do |input:|
+            forwarded_context = OmniAgent::Agent.__send__(:filter_forwarded_context, context, forward)
+            OmniAgent::Agent.__send__(:run_delegated_agent, agent_class, input, run_alias, forwarded_context)
+          end
+        end
+      end
+
       def with(context = nil, provider_override: nil, model_override: nil, options_override: {}, **context_keywords)
         merged_context = {}
         merged_context.merge!(context) if context.is_a?(Hash)
@@ -135,23 +167,6 @@ module OmniAgent
         as.to_s.split(/[_\s]+/).reject(&:empty?).map { |part| part[0].upcase + part[1..] }.join
       end
 
-      def build_delegated_tool_class(agent_class, description:, run_alias:, forward:)
-        tool_description = description || "Delegate to #{agent_class.name}."
-
-        Class.new(OmniAgent::Tool) do
-          description tool_description
-
-          input do
-            string :input, description: "Input/question to send to the delegated agent."
-          end
-
-          define_method(:execute) do |input:|
-            forwarded_context = OmniAgent::Agent.__send__(:filter_forwarded_context, context, forward)
-            OmniAgent::Agent.__send__(:run_delegated_agent, agent_class, input, run_alias, forwarded_context)
-          end
-        end
-      end
-
       def filter_forwarded_context(context, forward)
         return {} unless context.is_a?(Hash)
         return context.dup if forward == true
@@ -212,7 +227,11 @@ module OmniAgent
       @default_context = context_override || {}
     end
 
-    def run(input, context: {}, prompt_method: nil)
+    def stream
+      OmniAgent::Streaming::Proxy.new(self)
+    end
+
+    def run(input, context: {}, prompt_method: nil, &stream)
       context = @default_context.merge(context || {})
       bind_context_instance_variables(context)
 
@@ -237,13 +256,14 @@ module OmniAgent
                 "Increase OmniAgent.configuration.max_tool_iterations if more tool calls are expected."
         end
 
-        response = provider.chat(messages: messages, tools: filtered_tools, **@chat_options)
+        response = provider.chat(messages: messages, tools: filtered_tools, stream: stream, **@chat_options)
 
         if response.content && !response.tool_calls?
           messages << { role: "assistant", content: response.content }
           set_after_generation_state(response: response, messages: messages, initial_messages_count: initial_messages_count)
           run_after_generation_callbacks(input: input, context: context, messages: messages, response: response)
           sync_context_from_instance_variables(context)
+          stream&.call(OmniAgent::Streaming::Event.done(response))
           return response
         end
 
@@ -265,6 +285,8 @@ module OmniAgent
             tool_instance = tool_class.new
             tool_instance.context = context if tool_instance.respond_to?(:context=)
 
+            stream&.call(OmniAgent::Streaming::Event.tool_call(name: tool_name, arguments: tool_args, id: tool_id))
+
             begin
               result = tool_instance.invoke(tool_args)
 
@@ -274,13 +296,16 @@ module OmniAgent
                 name: tool_name,
                 content: result.to_s
               }
+              stream&.call(OmniAgent::Streaming::Event.tool_result(name: tool_name, id: tool_id, content: result.to_s))
             rescue => e
+              error_content = "Error executing tool: #{e.message}"
               messages << {
                 role: "tool",
                 tool_call_id: tool_id,
                 name: tool_name,
-                content: "Error executing tool: #{e.message}"
+                content: error_content
               }
+              stream&.call(OmniAgent::Streaming::Event.tool_result(name: tool_name, id: tool_id, content: error_content, error: true))
             end
 
             should_stop_generation ||= tool_class.respond_to?(:stops_generation?) && tool_class.stops_generation?
@@ -299,24 +324,14 @@ module OmniAgent
           set_after_generation_state(response: response, messages: messages, initial_messages_count: initial_messages_count)
           run_after_generation_callbacks(input: input, context: context, messages: messages, response: response)
           sync_context_from_instance_variables(context)
+          stream&.call(OmniAgent::Streaming::Event.done(response))
           return response
         end
       end
     end
 
     def available_tools
-      tool_namespace = "#{self.class.name}::Tools".safe_constantize
-
-      namespace_tools = if tool_namespace
-        tool_namespace.constants.filter_map do |const_name|
-          const = tool_namespace.const_get(const_name)
-          const if const.is_a?(Class) && const < OmniAgent::Tool
-        end
-      else
-        []
-      end
-
-      namespace_tools + self.class.configured_delegated_tool_classes
+      self.class.tool_classes
     end
 
     private

data/lib/omni_agent/configuration.rb

@@ -1,7 +1,8 @@
 module OmniAgent
   class Configuration
     attr_accessor :default_provider, :default_model, :max_retries, :retry_base_delay, :max_tool_iterations,
-                  :max_delegation_depth, :eval_judge_provider, :eval_judge_model, :eval_cache_enabled, :eval_cache_path
+                  :max_delegation_depth, :eval_judge_provider, :eval_judge_model, :eval_cache_enabled, :eval_cache_path,
+                  :mcp_allowed_origins, :mcp_max_request_bytes
 
     def initialize
       @default_provider = :openai
@@ -14,6 +15,8 @@ module OmniAgent
       @eval_judge_model = nil
       @eval_cache_enabled = true
       @eval_cache_path = "tmp/omni_agent_eval_cache.json"
+      @mcp_allowed_origins = []
+      @mcp_max_request_bytes = 1_048_576
     end
   end
 end

data/lib/omni_agent/engine.rb

@@ -1,5 +1,9 @@
 module OmniAgent
   class Engine < ::Rails::Engine
     isolate_namespace OmniAgent
+
+    initializer "omni_agent.mcp_routing" do
+      ActionDispatch::Routing::Mapper.include(OmniAgent::MCP::Routing)
+    end
   end
 end

data/lib/omni_agent/errors.rb

@@ -6,6 +6,7 @@ module OmniAgent
     class MaxToolIterationsError < Error; end
     class MaxDelegationDepthError < Error; end
     class EvalAssertionError < Error; end
+    class MCPError < Error; end
   end
 
   Error = Errors::Error
@@ -14,4 +15,5 @@ module OmniAgent
   MaxToolIterationsError = Errors::MaxToolIterationsError
   MaxDelegationDepthError = Errors::MaxDelegationDepthError
   EvalAssertionError = Errors::EvalAssertionError
+  MCPError = Errors::MCPError
 end

data/lib/omni_agent/mcp/authenticator.rb

@@ -0,0 +1,82 @@
+require "active_support/security_utils"
+
+module OmniAgent
+  module MCP
+    class Authenticator
+      Result = Struct.new(:authenticated, :principal) do
+        def authenticated?
+          authenticated == true
+        end
+      end
+
+      ARRAY_TOKEN_PRINCIPAL = :bearer_token
+
+      def initialize(server_class)
+        @server_class = server_class
+      end
+
+      def authenticate(request)
+        authentication = @server_class.configured_authentication
+
+        if authentication.nil?
+          raise OmniAgent::MCPError,
+                "#{@server_class.name} does not declare authentication. " \
+                "Add `authenticate :bearer, tokens: ...`, `authenticate { |request| ... }`, " \
+                "or explicitly opt out with `authenticate :none`."
+        end
+
+        case authentication[:strategy]
+        when :none
+          success(nil)
+        when :bearer
+          authenticate_bearer(request, authentication[:tokens])
+        when :custom
+          principal = authentication[:block].call(request)
+          principal ? success(principal) : failure
+        end
+      end
+
+      private
+
+      def authenticate_bearer(request, tokens)
+        presented = request.bearer_token
+        return failure if presented.nil?
+
+        matched = false
+        principal = nil
+
+        # Compare against every configured token (no early exit) so response
+        # timing does not reveal which token, or how many tokens, matched.
+        token_candidates(tokens).each do |candidate_principal, token|
+          next if token.nil? || token.to_s.empty?
+
+          if ActiveSupport::SecurityUtils.secure_compare(token.to_s, presented) && !matched
+            matched = true
+            principal = candidate_principal
+          end
+        end
+
+        matched ? success(principal) : failure
+      end
+
+      def token_candidates(tokens)
+        tokens = tokens.call if tokens.respond_to?(:call)
+
+        case tokens
+        when Hash
+          tokens.map { |principal, token| [ principal, token ] }
+        else
+          Array(tokens).map { |token| [ ARRAY_TOKEN_PRINCIPAL, token ] }
+        end
+      end
+
+      def success(principal)
+        Result.new(true, principal)
+      end
+
+      def failure
+        Result.new(false, nil)
+      end
+    end
+  end
+end