omni_agent 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c390e526b0bd6176f8755538304d0e0e99d9cc36627be1ee9b63119b53ce34
-  data.tar.gz: 4918452fbba6d30772abbf9d072d0c16cf363d5220a099183e9caa04d7481220
+  metadata.gz: f8a84d4b38e835bc00b73a88bc233932198498112e3837e33fdfdf3dbabab981
+  data.tar.gz: 6d5cd7709dc61be01ae892a67732b08ee3e17a6d4af7d81f8640f0fd618010e8
 SHA512:
-  metadata.gz: 522e4be90a757a9056e95cf45f5aafb1f18d7b6914e1ca667e32b3774ab70422f552e333ac2e340c4d1dab1c628350e04d494a9726b908467eb53723ae300dd6
-  data.tar.gz: c2c7939747237e554df0ac2569b84e36b164c1235f75fa876f04518cb644ad02579e18f4ee168c53ff55f32b75c8a58284ff921b217eda4b9148f67a8d5e4de7
+  metadata.gz: b56c77174212b7a4ba2e45b2b3bb6e0f384631fcdd2bcbf30e2a32c8edb1617b239e8bdd482dbb259baf48746b20c38d29fd325685262337e38ab1e9669a5220
+  data.tar.gz: 5fcb5179527eda96d3dc6726ad78c73b1bba4b3ef7c34825cbfec03c2437e7018647b43cf9f9d43791599efdc628530d5c6cfefcb6f431bd7548a97f7c9a8365

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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)
 
 

data/README.md

@@ -12,6 +12,7 @@ tool schemas, and generation lifecycle callbacks.
 - Agent callbacks (`before_generation`, `after_generation`)
 - Agent and tool tags to support filtering strategies
 - 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
@@ -240,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

@@ -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
@@ -316,18 +331,7 @@ module OmniAgent
     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

data/lib/omni_agent/mcp/handler.rb

@@ -0,0 +1,128 @@
+module OmniAgent
+  module MCP
+    class Handler
+      class ProtocolError < StandardError
+        attr_reader :code
+
+        def initialize(code, message)
+          super(message)
+          @code = code
+        end
+      end
+
+      def initialize(server)
+        @server = server
+      end
+
+      # Takes a parsed JSON-RPC message and returns the response Hash, or nil
+      # when no response is due (notifications and client responses).
+      def call(message)
+        unless message.is_a?(Hash)
+          reason = message.is_a?(Array) ? "Batch requests are not supported" : "Invalid Request"
+          return error_response(nil, INVALID_REQUEST, reason)
+        end
+
+        message = message.transform_keys(&:to_s)
+        return nil if client_response?(message)
+
+        id = message["id"]
+        notification = !message.key?("id")
+
+        unless message["jsonrpc"] == JSONRPC_VERSION && message["method"].is_a?(String)
+          return notification ? nil : error_response(id, INVALID_REQUEST, "Invalid Request")
+        end
+
+        return nil if notification
+
+        result = dispatch(message["method"], message["params"])
+        success_response(id, result)
+      rescue ProtocolError => e
+        error_response(id, e.code, e.message)
+      rescue StandardError => e
+        log_error("MCP internal error", e)
+        error_response(id, INTERNAL_ERROR, "Internal error")
+      end
+
+      private
+
+      attr_reader :server
+
+      def dispatch(method, params)
+        params = normalize_params(params)
+
+        case method
+        when "initialize" then initialize_result(params)
+        when "ping" then {}
+        when "tools/list" then tools_list_result
+        when "tools/call" then tools_call_result(params)
+        else
+          raise ProtocolError.new(METHOD_NOT_FOUND, "Method not found: #{method}")
+        end
+      end
+
+      def normalize_params(params)
+        return {} if params.nil?
+        raise ProtocolError.new(INVALID_PARAMS, "params must be an object") unless params.is_a?(Hash)
+
+        params.transform_keys(&:to_s)
+      end
+
+      def initialize_result(params)
+        requested = params["protocolVersion"]
+        protocol_version = SUPPORTED_PROTOCOL_VERSIONS.include?(requested) ? requested : LATEST_PROTOCOL_VERSION
+        server_class = server.class
+
+        result = {
+          protocolVersion: protocol_version,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: server_class.server_name, version: server_class.server_version }
+        }
+        result[:instructions] = server_class.instructions if server_class.instructions
+        result
+      end
+
+      def tools_list_result
+        tools = server.visible_tools.map { |name, tool_class| ToolAdapter.definition(name, tool_class) }
+        { tools: tools }
+      end
+
+      def tools_call_result(params)
+        name = params["name"]
+        raise ProtocolError.new(INVALID_PARAMS, "Missing tool name") unless name.is_a?(String)
+
+        tool_class = server.find_tool(name)
+        raise ProtocolError.new(INVALID_PARAMS, "Unknown tool: #{name}") unless tool_class
+
+        arguments = params["arguments"] || {}
+        raise ProtocolError.new(INVALID_PARAMS, "arguments must be an object") unless arguments.is_a?(Hash)
+
+        execute_tool(name, tool_class, arguments)
+      end
+
+      def execute_tool(name, tool_class, arguments)
+        tool = tool_class.new
+        tool.context = server.tool_context
+        ToolAdapter.result(tool.invoke(arguments))
+      rescue StandardError => e
+        log_error("MCP tool #{name} failed", e)
+        ToolAdapter.error_result("Error executing tool: #{e.message}")
+      end
+
+      def client_response?(message)
+        !message.key?("method") && (message.key?("result") || message.key?("error"))
+      end
+
+      def success_response(id, result)
+        { jsonrpc: JSONRPC_VERSION, id: id, result: result }
+      end
+
+      def error_response(id, code, message)
+        { jsonrpc: JSONRPC_VERSION, id: id, error: { code: code, message: message } }
+      end
+
+      def log_error(prefix, error)
+        MCP.logger&.error("[OmniAgent::MCP] #{prefix}: #{error.class}: #{error.message}")
+      end
+    end
+  end
+end

data/lib/omni_agent/mcp/rack_app.rb

@@ -0,0 +1,107 @@
+require "json"
+
+module OmniAgent
+  module MCP
+    # Streamable HTTP transport, stateless: every POST carries one JSON-RPC
+    # message and gets a plain JSON response. No SSE stream, no sessions.
+    class RackApp
+      JSON_HEADERS = { "content-type" => "application/json" }.freeze
+      PARSE_FAILED = Object.new.freeze
+
+      # Accepts the server class or its name. Passing a String defers the
+      # constant lookup to request time, which keeps routes reload-safe.
+      attr_reader :server
+
+      def initialize(server)
+        @server = server
+      end
+
+      def inspect
+        "#<#{self.class.name} #{server}>"
+      end
+
+      def call(env)
+        server_class = MCP.resolve_server_class(@server)
+        request = Request.new(env)
+
+        return forbidden unless origin_allowed?(request, server_class)
+
+        auth = Authenticator.new(server_class).authenticate(request)
+        return unauthorized(server_class) unless auth.authenticated?
+
+        return method_not_allowed unless request.post?
+
+        if request.protocol_version && !SUPPORTED_PROTOCOL_VERSIONS.include?(request.protocol_version)
+          return http_error(400, "Unsupported MCP-Protocol-Version: #{request.protocol_version}")
+        end
+
+        body = read_body(request)
+        return http_error(413, "Request body too large") if body.nil?
+
+        message = parse_json(body)
+        return json_response(400, parse_error_response) if message.equal?(PARSE_FAILED)
+
+        server = server_class.new(principal: auth.principal, request: request, transport: :http)
+        response = Handler.new(server).call(message)
+        return [ 202, {}, [] ] if response.nil?
+
+        status = response[:error] && response[:id].nil? ? 400 : 200
+        json_response(status, response)
+      end
+
+      private
+
+      def origin_allowed?(request, server_class)
+        origin = request.origin
+        return true if origin.nil? || origin.empty?
+
+        allowed = server_class.configured_allowed_origins + Array(OmniAgent.configuration.mcp_allowed_origins)
+        allowed.any? do |pattern|
+          pattern.is_a?(Regexp) ? pattern.match?(origin) : pattern.to_s == origin
+        end
+      end
+
+      def read_body(request)
+        max_bytes = OmniAgent.configuration.mcp_max_request_bytes
+        return nil if request.content_length.to_i > max_bytes
+
+        io = request.body
+        return "" if io.nil?
+
+        body = io.read(max_bytes + 1).to_s
+        body.bytesize > max_bytes ? nil : body
+      end
+
+      def parse_json(body)
+        JSON.parse(body)
+      rescue JSON::ParserError
+        PARSE_FAILED
+      end
+
+      def parse_error_response
+        { jsonrpc: JSONRPC_VERSION, id: nil, error: { code: PARSE_ERROR, message: "Parse error" } }
+      end
+
+      def json_response(status, payload)
+        [ status, JSON_HEADERS.dup, [ JSON.generate(payload) ] ]
+      end
+
+      def http_error(status, message)
+        json_response(status, { error: message })
+      end
+
+      def forbidden
+        http_error(403, "Origin not allowed")
+      end
+
+      def method_not_allowed
+        [ 405, JSON_HEADERS.merge("allow" => "POST"), [ JSON.generate({ error: "Method not allowed" }) ] ]
+      end
+
+      def unauthorized(server_class)
+        headers = JSON_HEADERS.merge("www-authenticate" => %(Bearer realm="#{server_class.server_name}"))
+        [ 401, headers, [ JSON.generate({ error: "Unauthorized" }) ] ]
+      end
+    end
+  end
+end

data/lib/omni_agent/mcp/request.rb

@@ -0,0 +1,24 @@
+require "rack"
+
+module OmniAgent
+  module MCP
+    class Request < Rack::Request
+      def bearer_token
+        header = get_header("HTTP_AUTHORIZATION").to_s
+        match = header.match(/\ABearer\s+(.+)\z/i)
+        return if match.nil?
+
+        token = match[1].strip
+        token.empty? ? nil : token
+      end
+
+      def protocol_version
+        get_header("HTTP_MCP_PROTOCOL_VERSION")
+      end
+
+      def origin
+        get_header("HTTP_ORIGIN")
+      end
+    end
+  end
+end

data/lib/omni_agent/mcp/routing.rb

@@ -0,0 +1,57 @@
+require "active_support/core_ext/string/inflections"
+
+module OmniAgent
+  module MCP
+    # Router helpers, included into ActionDispatch::Routing::Mapper by the engine.
+    #
+    #   mcp_server :support                        # SupportServer at /mcp/support
+    #   mcp_server :support, path: "/internal/mcp" # custom path
+    #   mcp_servers :support, :billing             # several at once
+    #   mcp_servers                                # every app/mcp_servers/**/*_server.rb
+    module Routing
+      DEFAULT_PATH_PREFIX = "/mcp".freeze
+
+      def mcp_server(name, path: nil, server: nil, as: nil)
+        slug = OmniAgent::MCP::Routing.slug_for(name)
+        server_name = server.is_a?(Class) ? server.name : (server || "#{slug}_server".camelize).to_s
+
+        mount OmniAgent::MCP::RackApp.new(server_name) => (path || "#{DEFAULT_PATH_PREFIX}/#{slug.dasherize}"),
+              as: (as || "#{slug.tr('/', '_')}_mcp_server")
+      end
+
+      def mcp_servers(*names, except: [], directory: nil)
+        names = names.flatten
+        names = OmniAgent::MCP::Routing.discover(directory || Rails.root.join("app", "mcp_servers")) if names.empty?
+        excluded = Array(except).map { |name| OmniAgent::MCP::Routing.slug_for(name) }
+
+        names.each do |name|
+          mcp_server(name) unless excluded.include?(OmniAgent::MCP::Routing.slug_for(name))
+        end
+      end
+
+      # :support, "support", "support_server", "SupportServer" -> "support"
+      # "Admin::SupportServer", "admin/support" -> "admin/support"
+      def self.slug_for(name)
+        name.to_s.underscore.delete_suffix("_server")
+      end
+
+      # Server slugs for every *_server.rb file, without loading any code.
+      # Skips files inside a server's own directory (e.g. support_server/tools/)
+      # and abstract base servers named application_*.
+      def self.discover(directory)
+        root = Pathname.new(directory.to_s)
+        return [] unless root.directory?
+
+        Dir.glob(root.join("**", "*_server.rb").to_s).sort.filter_map do |file|
+          relative = Pathname.new(file).relative_path_from(root).to_s.delete_suffix(".rb")
+          *dirs, base = relative.split("/")
+
+          next if dirs.any? { |dir| dir.end_with?("_server") }
+          next if base.start_with?("application_")
+
+          slug_for(relative)
+        end
+      end
+    end
+  end
+end

data/lib/omni_agent/mcp/server.rb

@@ -0,0 +1,238 @@
+require "active_support/core_ext/string/inflections"
+
+module OmniAgent
+  module MCP
+    class Server
+      TOOL_NAME_PATTERN = /\A[A-Za-z0-9_.-]{1,128}\z/
+
+      class << self
+        def server_name(value = nil)
+          @server_name = value.to_s if value
+          setting(:@server_name) || default_server_name
+        end
+
+        def server_version(value = nil)
+          @server_version = value.to_s if value
+          setting(:@server_version) || "0.1.0"
+        end
+
+        def instructions(text = nil)
+          @instructions = text if text
+          setting(:@instructions)
+        end
+
+        def tools(*tool_classes)
+          tool_classes.flatten.each { |tool_class| tool(tool_class) }
+        end
+
+        def tool(tool_class, as: nil)
+          add_tool_declaration(type: :tool, tool_class: tool_class, name: as&.to_s)
+        end
+
+        def tools_from(*agent_classes)
+          agent_classes.flatten.each do |agent_class|
+            add_tool_declaration(type: :agent_tools, agent_class: agent_class)
+          end
+        end
+
+        def expose_agent(agent_class, as:, description: nil, run_alias: nil, forward: [])
+          unless agent_class.is_a?(Class) && agent_class <= OmniAgent::Agent
+            raise ArgumentError, "expose_agent requires an OmniAgent::Agent subclass"
+          end
+
+          tool_class = OmniAgent::Agent.build_delegated_tool_class(
+            agent_class,
+            description: description,
+            run_alias: run_alias,
+            forward: forward
+          )
+
+          add_tool_declaration(type: :tool, tool_class: tool_class, name: as.to_s)
+        end
+
+        def authenticate(strategy = nil, tokens: nil, &block)
+          @authentication = if block
+            { strategy: :custom, block: block }
+          elsif strategy == :none
+            { strategy: :none }
+          elsif strategy == :bearer
+            raise ArgumentError, "authenticate :bearer requires tokens:" if tokens.nil?
+
+            { strategy: :bearer, tokens: tokens }
+          else
+            raise ArgumentError, "authenticate expects :bearer (with tokens:), :none, or a block"
+          end
+        end
+
+        def authorize_tool(&block)
+          raise ArgumentError, "authorize_tool requires a block" unless block
+
+          @authorize_tool_block = block
+        end
+
+        def context(&block)
+          raise ArgumentError, "context requires a block" unless block
+
+          @context_block = block
+        end
+
+        def stdio_principal(&block)
+          raise ArgumentError, "stdio_principal requires a block" unless block
+
+          @stdio_principal_block = block
+        end
+
+        def allowed_origins(*origins)
+          @allowed_origins = (@allowed_origins || []) + origins.flatten
+        end
+
+        def configured_tool_declarations; list_setting(:@tool_declarations); end
+        def configured_authentication; setting(:@authentication); end
+        def configured_authorize_tool_block; setting(:@authorize_tool_block); end
+        def configured_context_block; setting(:@context_block); end
+        def configured_stdio_principal_block; setting(:@stdio_principal_block); end
+        def configured_allowed_origins; list_setting(:@allowed_origins); end
+
+        # Ordered { "ToolName" => tool_class }: for each server in the
+        # inheritance chain, its <Server>::Tools namespace first, then its
+        # declared tools. Resolved on every call so lazily referenced tools
+        # (strings, tools_from, the Tools namespace) pick up code reloads.
+        def tool_registry
+          server_ancestors.reverse.each_with_object({}) do |server_class, registry|
+            entries = server_class.namespace_tool_classes.map { |tool_class| [ default_tool_name(tool_class), tool_class ] }
+            entries += (server_class.instance_variable_get(:@tool_declarations) || []).flat_map do |declaration|
+              resolve_declaration(declaration)
+            end
+
+            entries.each { |name, tool_class| register_tool(registry, name, tool_class) }
+          end
+        end
+
+        # Tools defined under this server's own namespace, e.g.
+        # app/mcp_servers/support_server/tools/*.rb -> SupportServer::Tools::*.
+        def namespace_tool_classes
+          return [] unless const_defined?(:Tools, false)
+
+          namespace = const_get(:Tools, false)
+          return [] unless namespace.is_a?(Module)
+
+          namespace.constants.sort.filter_map do |const_name|
+            const = namespace.const_get(const_name, false)
+            const if const.is_a?(Class) && const < OmniAgent::Tool
+          end
+        end
+
+        def resolve_stdio_principal
+          configured_stdio_principal_block&.call
+        end
+
+        private
+
+        # Servers inherit settings from parent servers (e.g. an ApplicationMCPServer
+        # that declares `authenticate` once). Scalars: nearest wins. Lists: concatenated.
+        def server_ancestors
+          ancestors.select { |klass| klass.is_a?(Class) && klass < OmniAgent::MCP::Server }
+        end
+
+        def setting(ivar)
+          server_ancestors.each do |klass|
+            value = klass.instance_variable_get(ivar)
+            return value unless value.nil?
+          end
+
+          nil
+        end
+
+        def list_setting(ivar)
+          server_ancestors.reverse.flat_map { |klass| klass.instance_variable_get(ivar) || [] }
+        end
+
+        def default_server_name
+          return "omni_agent" if name.nil?
+
+          base = name.demodulize.underscore
+          base = base.delete_suffix("_server") unless base == "server"
+          base
+        end
+
+        def add_tool_declaration(declaration)
+          @tool_declarations = (@tool_declarations || []) + [ declaration ]
+        end
+
+        def resolve_declaration(declaration)
+          case declaration[:type]
+          when :tool
+            tool_class = resolve_constant(declaration[:tool_class])
+            [ [ declaration[:name] || default_tool_name(tool_class), tool_class ] ]
+          when :agent_tools
+            agent_class = resolve_constant(declaration[:agent_class])
+            agent_class.tool_classes.map { |tool_class| [ default_tool_name(tool_class), tool_class ] }
+          end
+        end
+
+        def resolve_constant(value)
+          return value if value.is_a?(Class)
+
+          Object.const_get(value.to_s)
+        end
+
+        def default_tool_name(tool_class)
+          if tool_class.name.nil?
+            raise OmniAgent::MCPError, "Anonymous tool classes need an explicit name: `tool klass, as: \"name\"`"
+          end
+
+          tool_class.name.demodulize
+        end
+
+        def register_tool(registry, name, tool_class)
+          unless tool_class.is_a?(Class) && tool_class < OmniAgent::Tool
+            raise OmniAgent::MCPError, "#{tool_class.inspect} is not an OmniAgent::Tool subclass"
+          end
+
+          unless name.match?(TOOL_NAME_PATTERN)
+            raise OmniAgent::MCPError,
+                  "Invalid MCP tool name #{name.inspect} in #{self.name}: use 1-128 characters from A-Z, a-z, 0-9, _, -, ."
+          end
+
+          if registry.key?(name)
+            raise OmniAgent::MCPError,
+                  "Duplicate MCP tool name #{name.inspect} in #{self.name}. Use `tool klass, as: \"other_name\"` to rename one."
+          end
+
+          registry[name] = tool_class
+        end
+      end
+
+      attr_reader :principal, :request, :transport
+
+      def initialize(principal: nil, request: nil, transport: :http)
+        @principal = principal
+        @request = request
+        @transport = transport
+      end
+
+      def visible_tools
+        authorizer = self.class.configured_authorize_tool_block
+        registry = self.class.tool_registry
+        return registry unless authorizer
+
+        registry.select do |name, tool_class|
+          instance_exec(tool_class, principal, name, &authorizer)
+        end
+      end
+
+      def find_tool(name)
+        visible_tools[name.to_s]
+      end
+
+      def tool_context
+        base = { mcp_principal: principal, mcp_request: request }
+        context_block = self.class.configured_context_block
+        return base unless context_block
+
+        extra = instance_exec(principal, request, &context_block)
+        extra.is_a?(Hash) ? base.merge(extra) : base
+      end
+    end
+  end
+end

data/lib/omni_agent/mcp/stdio.rb

@@ -0,0 +1,56 @@
+require "json"
+
+module OmniAgent
+  module MCP
+    # stdio transport: newline-delimited JSON-RPC over stdin/stdout. Runs as a
+    # local subprocess of the client, so it skips HTTP authentication and takes
+    # its principal from the server's `stdio_principal` block instead.
+    class Stdio
+      # Entry point for `omni_agent mcp` and `rake omni_agent:mcp`. Keeps a
+      # private handle on the real stdout for the protocol, then points fd 1
+      # at stderr so stray `puts` or logger output cannot corrupt the stream.
+      def self.start(server, input: $stdin)
+        server_class = MCP.resolve_server_class(server)
+
+        protocol_output = $stdout.dup
+        $stdout.flush
+        $stdout.reopen($stderr)
+
+        new(server_class, input: input, output: protocol_output).run
+      end
+
+      def initialize(server, input:, output:)
+        @server_class = MCP.resolve_server_class(server)
+        @input = input
+        @output = output
+      end
+
+      def run
+        server = @server_class.new(principal: @server_class.resolve_stdio_principal, transport: :stdio)
+        handler = Handler.new(server)
+
+        @input.each_line do |line|
+          line = line.strip
+          next if line.empty?
+
+          message = begin
+            JSON.parse(line)
+          rescue JSON::ParserError
+            write(jsonrpc: JSONRPC_VERSION, id: nil, error: { code: PARSE_ERROR, message: "Parse error" })
+            next
+          end
+
+          response = handler.call(message)
+          write(response) if response
+        end
+      end
+
+      private
+
+      def write(payload)
+        @output.write("#{JSON.generate(payload)}\n")
+        @output.flush
+      end
+    end
+  end
+end

data/lib/omni_agent/mcp/tool_adapter.rb

@@ -0,0 +1,45 @@
+require "json"
+
+module OmniAgent
+  module MCP
+    module ToolAdapter
+      module_function
+
+      def definition(name, tool_class)
+        definition = { name: name }
+        definition[:title] = tool_class.title if tool_class.title
+        definition[:description] = tool_class.description
+        definition[:inputSchema] = tool_class.json_schema
+
+        annotations = tool_class.mcp_annotations
+        definition[:annotations] = annotations unless annotations.empty?
+
+        definition
+      end
+
+      def result(value)
+        case value
+        when nil
+          { content: [ text_content("") ] }
+        when String
+          { content: [ text_content(value) ] }
+        when Hash
+          json = JSON.generate(value)
+          { content: [ text_content(json) ], structuredContent: JSON.parse(json) }
+        when Array
+          { content: [ text_content(JSON.generate(value)) ] }
+        else
+          { content: [ text_content(value.to_s) ] }
+        end
+      end
+
+      def error_result(message)
+        { content: [ text_content(message) ], isError: true }
+      end
+
+      def text_content(text)
+        { type: "text", text: text }
+      end
+    end
+  end
+end

data/lib/omni_agent/mcp.rb

@@ -0,0 +1,31 @@
+module OmniAgent
+  module MCP
+    SUPPORTED_PROTOCOL_VERSIONS = [ "2025-11-25", "2025-06-18", "2025-03-26" ].freeze
+    LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS.first
+
+    JSONRPC_VERSION = "2.0".freeze
+
+    PARSE_ERROR = -32_700
+    INVALID_REQUEST = -32_600
+    METHOD_NOT_FOUND = -32_601
+    INVALID_PARAMS = -32_602
+    INTERNAL_ERROR = -32_603
+
+    def self.logger
+      return unless defined?(Rails) && Rails.respond_to?(:logger)
+
+      Rails.logger
+    end
+
+    def self.resolve_server_class(server)
+      return server if server.is_a?(Class)
+
+      server_class = Object.const_get(server.to_s)
+      unless server_class.is_a?(Class) && server_class < OmniAgent::MCP::Server
+        raise OmniAgent::MCPError, "#{server} is not an OmniAgent::MCP::Server subclass"
+      end
+
+      server_class
+    end
+  end
+end

data/lib/omni_agent/tool.rb

@@ -11,6 +11,31 @@ module OmniAgent
         @metadata || {}
       end
 
+      def title(text = nil)
+        @title = text if text
+        @title
+      end
+
+      def annotations(read_only: nil, destructive: nil, idempotent: nil, open_world: nil)
+        @annotations = {
+          read_only: read_only,
+          destructive: destructive,
+          idempotent: idempotent,
+          open_world: open_world
+        }.compact
+      end
+
+      def mcp_annotations
+        hints = @annotations || {}
+
+        {
+          readOnlyHint: hints[:read_only],
+          destructiveHint: hints[:destructive],
+          idempotentHint: hints[:idempotent],
+          openWorldHint: hints[:open_world]
+        }.compact
+      end
+
       def tags(*tag_names)
         return @tags || [] if tag_names.empty?
 

data/lib/omni_agent/version.rb

@@ -1,3 +1,3 @@
 module OmniAgent
-  VERSION = "0.1.9"
+  VERSION = "0.1.10"
 end

data/lib/omni_agent.rb

@@ -3,7 +3,7 @@ require "omni_agent/engine" if defined?(Rails)
 require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem
-loader.inflector.inflect("openai" => "OpenAI", "cli" => "CLI")
+loader.inflector.inflect("openai" => "OpenAI", "cli" => "CLI", "mcp" => "MCP")
 loader.ignore(File.expand_path("generators", __dir__))
 loader.setup
 

data/lib/tasks/omni_agent_mcp_tasks.rake

@@ -0,0 +1,9 @@
+namespace :omni_agent do
+  desc 'Run an MCP server over stdio. Usage: rake "omni_agent:mcp[SupportServer]"'
+  task :mcp, [ :server ] => :environment do |_task, args|
+    server = args[:server].to_s.strip
+    abort 'Please provide a server class. Example: bin/rails "omni_agent:mcp[SupportServer]"' if server.empty?
+
+    OmniAgent::MCP::Stdio.start(server)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omni_agent
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - ACR1209
@@ -62,6 +62,7 @@ files:
 - lib/generators/omni_agent/agent/agent_generator.rb
 - lib/generators/omni_agent/eval/eval_generator.rb
 - lib/generators/omni_agent/install/install_generator.rb
+- lib/generators/omni_agent/mcp_server/mcp_server_generator.rb
 - lib/omni_agent.rb
 - lib/omni_agent/agent.rb
 - lib/omni_agent/configuration.rb
@@ -81,6 +82,15 @@ files:
 - lib/omni_agent/eval/run.rb
 - lib/omni_agent/eval/runner.rb
 - lib/omni_agent/eval/tool_call_assertion.rb
+- lib/omni_agent/mcp.rb
+- lib/omni_agent/mcp/authenticator.rb
+- lib/omni_agent/mcp/handler.rb
+- lib/omni_agent/mcp/rack_app.rb
+- lib/omni_agent/mcp/request.rb
+- lib/omni_agent/mcp/routing.rb
+- lib/omni_agent/mcp/server.rb
+- lib/omni_agent/mcp/stdio.rb
+- lib/omni_agent/mcp/tool_adapter.rb
 - lib/omni_agent/providers.rb
 - lib/omni_agent/providers/base.rb
 - lib/omni_agent/providers/mock.rb
@@ -96,6 +106,7 @@ files:
 - lib/omni_agent/tool/schema_builder.rb
 - lib/omni_agent/version.rb
 - lib/tasks/omni_agent_eval_tasks.rake
+- lib/tasks/omni_agent_mcp_tasks.rake
 homepage: https://github.com/ACR1209/omni_agent
 licenses:
 - MIT