omni_agent 0.1.10 → 0.2.0

data/docs/mcp/authentication.md

@@ -0,0 +1,226 @@
+<!-- Generated from omniagent-docs/docs/mcp/authentication.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/mcp/authentication -->
+
+# Authentication
+
+An MCP server mounted over HTTP lets anyone who can reach the URL run your tools. For that reason, **every server must declare `authenticate`**. A server without it raises `OmniAgent::MCPError` on the first HTTP request. To make a server public on purpose, write `authenticate :none`.
+
+Authentication returns a **principal**: the identity of the caller. The principal is passed to [`authorize_tool`](defining-servers.md#per-principal-tool-access), to the [`context`](defining-servers.md#tool-context) block, and to tools as `context[:mcp_principal]`.
+
+Requests that fail authentication get `401 Unauthorized` with `WWW-Authenticate: Bearer realm="<server_name>"`. [OAuth 2.1](#oauth-21) servers add more detail to that header.
+
+## Static Bearer Tokens
+
+```ruby
+authenticate :bearer, tokens: -> { ENV.fetch("SUPPORT_MCP_TOKENS", "").split(",") }
+```
+
+Clients send `Authorization: Bearer <token>`. `tokens:` accepts:
+
+* **An Array**: Any listed token is accepted. The principal is `:bearer_token`.
+* **A Hash of `principal => token`**: The principal is the matching key. Use it to tell callers apart:
+
+  ```ruby
+  authenticate :bearer, tokens: -> { { "ci" => ENV["CI_MCP_TOKEN"], "ops" => ENV["OPS_MCP_TOKEN"] } }
+  ```
+
+* **A Proc that returns either of the above**: The proc runs on every request, so you can rotate tokens in the environment or in credentials without restarting the server. Use a proc whenever you read tokens from `ENV`.
+
+Tokens are compared with `ActiveSupport::SecurityUtils.secure_compare`. Every configured token is checked, with no early exit. Blank tokens are ignored, so an unset environment variable never matches an empty `Authorization` header.
+
+## Custom Authentication
+
+Pass a block to authenticate against your own data. The block receives an `OmniAgent::MCP::Request` (a `Rack::Request` that also has `#bearer_token`). Return the principal, or `nil`/`false` to reject the request:
+
+```ruby
+authenticate do |request|
+  User.find_by(api_token: request.bearer_token)
+end
+```
+
+The returned user is then the principal everywhere:
+
+```ruby
+authorize_tool { |tool_class, user| user.admin? || !tool_class.tags.include?(:admin) }
+context { |user, _request| { current_user: user } }
+```
+
+## OAuth 2.1
+
+`authenticate :oauth` implements the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization). Your MCP server is an OAuth 2.1 **resource server**: an external **authorization server** (Auth0, Keycloak, Okta, Entra ID, WorkOS, Doorkeeper, ...) signs users in and issues access tokens, and OmniAgent validates those tokens on every request. MCP clients such as Claude Code, Claude Desktop and the MCP Inspector discover the authorization server and run the OAuth flow by themselves, so users never copy tokens by hand.
+
+```ruby
+class SupportServer < OmniAgent::MCP::Server
+  authenticate :oauth,
+               resource: "https://app.example.com/mcp/support",
+               authorization_servers: "https://auth.example.com",
+               scopes: %w[mcp:tools],
+               jwks_uri: "https://auth.example.com/.well-known/jwks.json" do |access_token, _request|
+    User.find_by(oauth_subject: access_token.subject)
+  end
+end
+```
+
+OmniAgent does not include an authorization server. Use your identity provider, or a gem such as Doorkeeper in your app. The MCP specification expects it to support PKCE and to accept the `resource` parameter ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707)), so that tokens name your server as their audience.
+
+### Options
+
+* **`resource:`** (required): The canonical URL of this MCP endpoint, as clients connect to it. Tokens must list it in `aud`. It is configured rather than read from the `Host` header, so a token for another server cannot be replayed by changing that header.
+* **`authorization_servers:`** (required): One or more issuer URLs. They are published in the metadata, and a token's `iss` must be one of them.
+* **`scopes:`**: Scopes every token must have. Defaults to none. A valid token that lacks one gets `403` with `error="insufficient_scope"`.
+* **`scopes_supported:`**: Scopes advertised in the metadata. Defaults to `scopes:`.
+* **`audience:`**: Accept this `aud` value instead of `resource:`. Use it when your authorization server issues a fixed API identifier (for example `api://support`).
+* **Exactly one way to validate tokens**: `jwks_uri:`, `introspection:` or `verify_token:`. See below.
+
+`resource:`, `authorization_servers:`, `audience:` and the `introspection:` values also accept a Proc, which runs on every request:
+
+```ruby
+authenticate :oauth, resource: -> { ENV.fetch("SUPPORT_MCP_URL") }, ...
+```
+
+### Validating Tokens
+
+**JWT access tokens** ([RFC 9068](https://www.rfc-editor.org/rfc/rfc9068)), checked against the authorization server's public keys. Add `gem "jwt"` to your Gemfile:
+
+```ruby
+authenticate :oauth, ..., jwks_uri: "https://auth.example.com/.well-known/jwks.json"
+```
+
+The signature, `exp`, `nbf` and `iss` are checked. Tokens must contain `exp` and `iss`. Only asymmetric algorithms (`RS*`, `PS*`, `ES*`) are accepted; change them with `algorithms:`. The key set is cached for 5 minutes. A token with an unknown `kid` refetches it (key rotation), at most every 30 seconds. One request refreshes the keys while the others keep using the cached ones. If the authorization server cannot be reached, OmniAgent keeps using the cached keys, or, if it has none yet, rejects requests with `401` right away and tries again after 30 seconds.
+
+**Token introspection** ([RFC 7662](https://www.rfc-editor.org/rfc/rfc7662)), for opaque tokens. Every request asks the authorization server whether the token is active:
+
+```ruby
+authenticate :oauth, ...,
+             introspection: {
+               url: "https://auth.example.com/oauth/introspect",
+               client_id: -> { Rails.application.credentials.mcp_client_id },
+               client_secret: -> { Rails.application.credentials.mcp_client_secret }
+             }
+```
+
+> **Warning: Introspection responses must include `aud`**
+>
+> Every token must name your server in `aud` (see below), but many introspection endpoints leave it out. Doorkeeper, for example, does not return it by default, so every request gets `401` and nothing explains why. Add it to the response. With Doorkeeper, use `custom_introspection_response`:
+>
+> ```ruby
+> # config/initializers/doorkeeper.rb
+> Doorkeeper.configure do
+>   custom_introspection_response do |_token, _context|
+>     { aud: "https://app.example.com/mcp/support" }
+>   end
+> end
+> ```
+
+An MCP session sends many requests, and each one calls the introspection endpoint. If that becomes a problem, cache the result yourself with `verify_token:`. A revoked token keeps working until its cache entry expires, so keep the expiry short:
+
+```ruby
+introspector = OmniAgent::MCP::OAuth::IntrospectionVerifier.new(
+  url: "https://auth.example.com/oauth/introspect",
+  client_id: -> { Rails.application.credentials.mcp_client_id },
+  client_secret: -> { Rails.application.credentials.mcp_client_secret }
+)
+
+authenticate :oauth, ...,
+             verify_token: ->(token) {
+               Rails.cache.fetch("mcp_token/#{Digest::SHA256.hexdigest(token)}", expires_in: 1.minute) do
+                 introspector.call(token)
+               end
+             }
+```
+
+**Custom verification**, when you already have the logic. The block receives the raw token (and, optionally, the request) and returns the token's claims as a Hash, or `nil` to reject it:
+
+```ruby
+authenticate :oauth, ...,
+             verify_token: ->(token) {
+               record = OAuthToken.active.find_by(digest: Digest::SHA256.hexdigest(token))
+               record && { "sub" => record.user_id.to_s, "aud" => record.resource,
+                           "scope" => record.scopes, "exp" => record.expires_at.to_i }
+             }
+```
+
+Whatever the method, OmniAgent then checks the claims: `aud` must contain `resource:` (or `audience:`), `exp` and `nbf` must be current (30 seconds of clock skew allowed), `iss` (if present) must be one of `authorization_servers:`, and `scope` (or `scp`) must contain every scope in `scopes:`. If the authorization server cannot be reached, the request gets `401` and the error is logged.
+
+Exceptions raised by your own code, in `verify_token:` or in the block that returns the principal (for example a database error in `User.find_by`), are not caught. The request gets `500`, not `401`.
+
+### The Principal and the Access Token
+
+The validated token is an `OmniAgent::MCP::OAuth::AccessToken`, with `#subject`, `#client_id`, `#issuer`, `#audience`, `#scopes`, `#scope?(*names)`, `#expires_at` and `#claims`.
+
+Without a block, the access token is the principal. With a block, the block's return value is the principal; return `nil` to reject the request. Either way, the token is available as `access_token` inside `authorize_tool` and `context`, and to tools as `context[:mcp_access_token]`. Use it to require extra scopes for some tools:
+
+```ruby
+authorize_tool { |tool_class, _user| !tool_class.tags.include?(:admin) || access_token.scope?("mcp:admin") }
+```
+
+### Discovery
+
+Clients find the authorization server through Protected Resource Metadata ([RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)). OmniAgent serves it under the endpoint, with no authentication and with CORS enabled for browser-based clients:
+
+```bash
+curl https://app.example.com/mcp/support/.well-known/oauth-protected-resource
+```
+
+```json
+{
+  "resource": "https://app.example.com/mcp/support",
+  "authorization_servers": ["https://auth.example.com"],
+  "scopes_supported": ["mcp:tools"],
+  "bearer_methods_supported": ["header"],
+  "resource_name": "support"
+}
+```
+
+Responses that reject a token point clients to it:
+
+| Case | Status | `WWW-Authenticate` |
+|---|---|---|
+| No token | `401` | `Bearer realm="support", resource_metadata="https://app.example.com/mcp/support/.well-known/oauth-protected-resource", scope="mcp:tools"` |
+| Invalid, expired or wrong-audience token | `401` | Same, plus `error="invalid_token"` |
+| Missing scope | `403` | Same, plus `error="insufficient_scope"` |
+
+Tokens are only read from the `Authorization` header, never from the query string.
+
+## No Authentication
+
+```ruby
+authenticate :none
+```
+
+Every request is accepted and the principal is `nil`. Use this only for servers that are not reachable from outside your machine or network, or for tools that are safe for anyone to run.
+
+## stdio
+
+The stdio transport runs as a local subprocess that the MCP client starts. It already has your shell's access, so it does **not** run `authenticate`. Use `stdio_principal` to choose who the local caller is:
+
+```ruby
+stdio_principal { User.find_by(email: ENV["MCP_USER_EMAIL"]) }
+```
+
+The block runs once when the process starts. Without it, the principal is `nil`. `authorize_tool` and `context` still apply over stdio.
+
+## Origin Checks
+
+Browsers send an `Origin` header. A malicious web page can use DNS rebinding to make a browser send requests to a server on `localhost`. For this reason, the MCP specification requires servers to check `Origin`. OmniAgent rejects requests that have an `Origin` header that is not in the allowlist with `403 Forbidden`. Requests without an `Origin` header are allowed. CLI and desktop clients do not send one.
+
+If a browser-based client must call your server, allow its origin on the server or globally:
+
+```ruby
+class SupportServer < OmniAgent::MCP::Server
+  allowed_origins "https://inspector.example.com", %r{\Ahttps://.*\.mycompany\.com\z}
+end
+
+OmniAgent.configure do |config|
+  config.mcp_allowed_origins = [ "https://inspector.example.com" ]
+end
+```
+
+## Security Checklist
+
+* Serve the endpoint over **HTTPS** in production. Bearer tokens in plain HTTP can be read by anyone on the network.
+* Give each client its own token (Hash form) so you can revoke one without affecting the others.
+* Hide destructive or expensive tools (such as [exposed agents](defining-servers.md#exposing-agents)) with `authorize_tool`.
+* Tool error messages are returned to the client. Do not put secrets in exception messages.
+* Request bodies larger than `mcp_max_request_bytes` (default 1 MiB) are rejected with `413`. See [Configuration](../configuration.md).
+* With [OAuth 2.1](#oauth-21), set `resource:` to the exact public URL of the endpoint, and keep `scopes:` minimal.

data/docs/mcp/defining-servers.md

@@ -0,0 +1,196 @@
+<!-- Generated from omniagent-docs/docs/mcp/defining-servers.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/mcp/defining-servers -->
+
+# Defining MCP Servers
+
+The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) lets AI clients such as Claude Code, Claude Desktop and Cursor call tools that live in your app. `OmniAgent::MCP::Server` turns the `OmniAgent::Tool` classes you already wrote for your agents — and the agents themselves — into an MCP server, with no extra gem.
+
+v1 supports MCP **tools** only (no resources or prompts), over [Streamable HTTP and stdio](transports.md).
+
+A server gets its tools in two ways, and you can use both together:
+
+* **Its own `tools/` directory**: tools that only this server uses. They are added automatically, like agent tools.
+* **The DSL**: `tools`, `tool`, `tools_from` and `expose_agent` reuse tools and agents that you already have.
+
+## Generate a Server
+
+```bash
+rails generate omni_agent:mcp_server Support --agents SupportAgent
+```
+
+This creates `app/mcp_servers/support_server.rb` and mounts it at `/mcp/support`. Add `--with-tools LookupOrder RefundOrder` to also scaffold server tools. See [Generators](../generators.md#mcp-server-generator) for every option.
+
+## The Server Tools Directory
+
+Put tools that belong only to the server in `app/mcp_servers/<server_name>/tools/`, namespaced under `<ServerClass>::Tools`:
+
+```text
+app/mcp_servers/
+├── support_server.rb
+└── support_server/
+    └── tools/
+        ├── lookup_order.rb
+        └── refund_order.rb
+```
+
+```ruby
+# app/mcp_servers/support_server/tools/lookup_order.rb
+module SupportServer::Tools
+  class LookupOrder < OmniAgent::Tool
+    description "Find an order by number."
+    annotations read_only: true
+
+    input do
+      string :number, description: "Order number"
+    end
+
+    def execute(number:)
+      Order.find_by!(number: number).as_json(only: %i[number status total])
+    end
+  end
+end
+```
+
+Every `OmniAgent::Tool` subclass in `SupportServer::Tools` is exposed under its class name (`LookupOrder`). There is nothing to register. Rails autoloads these files and reloads them in development, so new or changed tools appear on the next request.
+
+Directory tools are listed first, sorted by name, followed by the tools you declare with the DSL. A server that inherits from another server also gets the parent's directory tools.
+
+## The Server DSL
+
+```ruby
+# app/mcp_servers/support_server.rb
+class SupportServer < OmniAgent::MCP::Server
+  server_name "support"            # default: underscored class name minus _server
+  server_version "1.0.0"           # default: "0.1.0"
+  instructions "Tools for the support team."
+
+  tools ResearchAgent::Tools::GetWeather, TaskAgent::Tools::SetPriority
+  tool  TaskAgent::Tools::AssignTicket, as: "assign_ticket"
+  tools_from TaskAgent
+  expose_agent ResearchAgent, as: :research, description: "Ask the research agent", forward: [ :current_user ]
+
+  authenticate :bearer, tokens: -> { ENV.fetch("SUPPORT_MCP_TOKENS", "").split(",") }
+  authorize_tool { |tool_class, principal| principal.admin? || !tool_class.tags.include?(:admin) }
+  context { |principal, request| { current_user: principal } }
+end
+```
+
+* **`server_name`** / **`server_version`**: Reported to the client in `serverInfo` during the `initialize` handshake.
+* **`instructions`**: Optional text the client can show to its model, describing how to use your tools.
+* **`<ServerClass>::Tools`**: Added automatically. See [The Server Tools Directory](#the-server-tools-directory).
+* **`tools`**: One or more `OmniAgent::Tool` classes. Each is exposed under its demodulized class name (`ResearchAgent::Tools::GetWeather` → `GetWeather`), the same name agents use.
+* **`tool klass, as:`**: Expose a single tool under a different name.
+* **`tools_from AgentClass`**: Expose every tool the agent has — its `<AgentClass>::Tools` namespace plus any [`delegate_to`](../agent/delegation.md) tools. Resolved on each request, so new tools show up without editing the server.
+* **`expose_agent`**: Expose a whole agent as a single tool. See [Exposing Agents](#exposing-agents).
+* **`authenticate`**: Required for HTTP. See [Authentication](authentication.md).
+* **`authorize_tool`** / **`context`**: See [Per-Principal Tool Access](#per-principal-tool-access) and [Tool Context](#tool-context).
+
+Tool classes can also be passed as strings (`tools "ResearchAgent::Tools::GetWeather"`). They are resolved when the tool list is built, which helps if the server file loads before your agents.
+
+### Tool Names
+
+MCP tool names must be 1–128 characters from `A-Z a-z 0-9 _ - .`. Two tools with the same name raise `OmniAgent::MCPError`, including a directory tool and a declared tool. If two agents both define a `Search` tool, rename one:
+
+```ruby
+tools_from DocsAgent
+tool TicketsAgent::Tools::Search, as: "search_tickets"
+```
+
+### Sharing Configuration
+
+Servers inherit from parent servers. Settings (`authenticate`, `authorize_tool`, `context`, `stdio_principal`, `instructions`, `server_version`) use the nearest declaration. Tools and allowed origins add up:
+
+```ruby
+class ApplicationMcpServer < OmniAgent::MCP::Server
+  authenticate { |request| User.find_by(api_token: request.bearer_token) }
+  context { |principal, _request| { current_user: principal } }
+end
+
+class SupportServer < ApplicationMcpServer
+  tools_from SupportAgent
+end
+```
+
+## Tool Annotations
+
+MCP clients use optional hints to decide, for example, whether to ask the user before a call. Declare them on the tool class:
+
+```ruby
+class GetWeather < OmniAgent::Tool
+  title "Get weather"
+  annotations read_only: true, destructive: false, idempotent: true, open_world: true
+end
+```
+
+| DSL key | MCP annotation | Meaning |
+|---|---|---|
+| `read_only:` | `readOnlyHint` | The tool does not change anything |
+| `destructive:` | `destructiveHint` | The tool can delete or overwrite data |
+| `idempotent:` | `idempotentHint` | Calling it again with the same arguments has no extra effect |
+| `open_world:` | `openWorldHint` | The tool talks to external systems |
+
+`title` is a human-friendly display name. Neither `title` nor `annotations` is sent to LLM providers when the tool is used by an agent. Clients treat annotations as hints, not as guarantees, so do not rely on them for security.
+
+## How Calls Work
+
+* `tools/list` returns each tool's name, `title`, `description`, `inputSchema` (the same JSON schema built by `input do ... end`) and annotations.
+* `tools/call` creates a new tool instance, sets its `context`, and calls `invoke` with the client's arguments. Arguments are validated exactly as they are for agents.
+* **Return values**: a `String` becomes text content. A `Hash` becomes JSON text plus `structuredContent`. An `Array` becomes JSON text. `nil` becomes empty text. Any other value is converted with `to_s`.
+* **Errors**: Validation failures (`ArgumentError`) and exceptions raised by `#execute` return a tool result with `isError: true` and the text `Error executing tool: <message>`, the same text agents receive. The model can then correct its arguments. Errors are logged to `Rails.logger`.
+* An unknown tool name, or a tool the principal may not use, returns JSON-RPC error `-32602`.
+
+## Exposing Agents
+
+`expose_agent` wraps an agent as one tool with a single `input` string argument. It works like [`delegate_to`](../agent/delegation.md): the agent runs its full loop, including its own tool calls, and returns its final answer as the tool result.
+
+```ruby
+expose_agent ResearchAgent, as: :research,
+                            description: "Ask the research agent",
+                            run_alias: :summarize,
+                            forward: [ :current_user ]
+```
+
+* **`as:`**: The MCP tool name, used as given (`:research` → `research`).
+* **`description:`**: Defaults to `"Delegate to <AgentClass>."`.
+* **`run_alias:`**: Call a [run entrypoint](../agent/run-entrypoints.md) instead of `run`.
+* **`forward:`**: Tool context keys passed to the agent's `context:`. Use `true` for all keys. The default is `[]` (no context). Combine with the [`context`](#tool-context) block to give the agent the current user.
+
+Each call to an exposed agent is a call to your LLM provider, so it costs money. Protect these tools with authentication and, if needed, `authorize_tool`.
+
+## Per-Principal Tool Access
+
+`authorize_tool` decides which tools each principal can see and call. It receives the tool class, the principal returned by [authentication](authentication.md) and the registered tool name. It runs for both `tools/list` and `tools/call`. A hidden tool is reported as unknown.
+
+```ruby
+authorize_tool do |tool_class, principal, name|
+  next true if principal.admin?
+
+  !tool_class.tags.include?(:admin) && name != "research"
+end
+```
+
+The block runs on the server instance, so `transport` (`:http` or `:stdio`) and `request` are also available.
+
+## Tool Context
+
+Every MCP tool call sets `tool.context` to:
+
+```ruby
+{ mcp_principal: principal, mcp_request: request } # request is nil over stdio
+```
+
+With [`authenticate :oauth`](authentication.md#oauth-21), it also includes `mcp_access_token`, the validated `OmniAgent::MCP::OAuth::AccessToken`.
+
+The `context` block merges extra keys. Use it to give tools that you share with agents the same keys that the agents give them:
+
+```ruby
+context { |principal, request| { current_user: principal, ip: request&.ip } }
+```
+
+```ruby
+class SetPriority < OmniAgent::Tool
+  def execute(ticket:, priority:)
+    Ticket.find(ticket).update!(priority: priority, updated_by: context[:current_user])
+  end
+end
+```

data/docs/mcp/transports.md

@@ -0,0 +1,166 @@
+<!-- Generated from omniagent-docs/docs/mcp/transports.mdx by `bundle exec rake docs:sync`. Do not edit by hand. -->
+<!-- Online version: https://omniagent.activetaskers.com/docs/mcp/transports -->
+
+# Transports and Clients
+
+OmniAgent supports both MCP transports:
+
+* **Streamable HTTP**: Mount the server in your routes with `mcp_server`. Remote clients connect to the URL.
+* **stdio**: The client starts your app as a subprocess and talks to it over stdin and stdout. Use it for local development.
+
+Both transports run the same server class.
+
+## Streamable HTTP
+
+Mount servers in `config/routes.rb` with the `mcp_server` and `mcp_servers` route helpers:
+
+```ruby
+Rails.application.routes.draw do
+  mcp_server :support                          # SupportServer at /mcp/support
+  mcp_server :billing, path: "/internal/mcp"   # BillingServer at a custom path
+  mcp_server "admin/reports"                   # Admin::ReportsServer at /mcp/admin/reports
+  mcp_servers :inventory, :shipping            # several servers at once
+end
+```
+
+The name is converted to the class name `<Name>Server`, and the default path is `/mcp/<name>`. Underscores in the path become dashes (`:customer_support` → `/mcp/customer-support`). Each route is named `<name>_mcp_server`, so you can use `support_mcp_server_url` to build the URL.
+
+| Option | Default | Meaning |
+|---|---|---|
+| `path:` | `/mcp/<name>` | Mount path |
+| `server:` | `"<Name>Server"` | Server class or class name, for servers that do not follow the naming convention |
+| `as:` | `<name>_mcp_server` | Route name |
+
+### Mount Every Server
+
+Call `mcp_servers` with no names to mount every server in `app/mcp_servers/` at its default path:
+
+```ruby
+Rails.application.routes.draw do
+  mcp_servers
+end
+```
+
+* Every `*_server.rb` file is mounted, including files in subdirectories (`admin/reports_server.rb` → `/mcp/admin/reports`).
+* Files inside a server's own directory, such as `support_server/tools/`, are skipped.
+* Abstract base servers whose file name starts with `application_` (for example, `application_mcp_server.rb`) are skipped.
+* Use `except:` to skip other servers. To give one server a custom path, skip it and mount it separately:
+
+  ```ruby
+  mcp_servers except: [ :billing ]
+  mcp_server :billing, path: "/internal/mcp"
+  ```
+
+With this form, adding a server file adds an endpoint without a change to `routes.rb`. Every endpoint still requires [authentication](authentication.md), but review new server files with that in mind.
+
+### Lazy Loading
+
+The helpers do not load your server classes. Each request looks up the class by name, so code reloading works in development and the routes file does not load your tools before your agents. `mcp_server` is shorthand for this lower-level form, which you can still use:
+
+```ruby
+mount OmniAgent::MCP::RackApp.new("SupportServer") => "/mcp/support"
+```
+
+The endpoint is **stateless**:
+
+* Each `POST` carries one JSON-RPC message and gets one JSON response (`200`). Notifications get `202 Accepted` with no body.
+* There are no sessions (`Mcp-Session-Id`) and no server-sent event stream. `GET` and `DELETE` return `405 Method Not Allowed`. The MCP specification allows both choices.
+* Because there is no session state, the server works behind a load balancer with several Puma workers or hosts.
+* Servers that use [`authenticate :oauth`](authentication.md#oauth-21) also answer `GET <endpoint>/.well-known/oauth-protected-resource` with their Protected Resource Metadata.
+
+| Status | When |
+|---|---|
+| `200` | JSON-RPC response (including tool errors with `isError: true`) |
+| `202` | Notification or client response accepted |
+| `400` | Invalid JSON (`-32700`), invalid JSON-RPC message, or unsupported `MCP-Protocol-Version` header |
+| `401` | Authentication failed |
+| `403` | `Origin` header not allowed, or the OAuth token lacks a required scope (`error="insufficient_scope"`) |
+| `405` | Method other than `POST` |
+| `413` | Body larger than `mcp_max_request_bytes` |
+
+Supported protocol versions are `2025-11-25`, `2025-06-18` and `2025-03-26`.
+
+### Try It With curl
+
+```bash
+SUPPORT_MCP_TOKENS=secret bin/rails server
+
+curl -s localhost:3000/mcp/support \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer secret' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+## stdio
+
+Run the server from your Rails app root:
+
+```bash
+bundle exec omni_agent mcp SupportServer
+# or
+bin/rails "omni_agent:mcp[SupportServer]"
+```
+
+The process reads one JSON-RPC message per line from stdin and writes one response per line to stdout. Anything else written to stdout would corrupt the protocol, so OmniAgent redirects stdout to stderr after it boots. `puts` calls and loggers that write to stdout then go to stderr. The process exits when the client closes stdin.
+
+stdio does not use `authenticate`. See [stdio authentication](authentication.md#stdio).
+
+## Connecting Clients
+
+### Claude Code
+
+Over HTTP:
+
+```bash
+claude mcp add --transport http support https://myapp.example.com/mcp/support \
+  --header "Authorization: Bearer $SUPPORT_MCP_TOKEN"
+```
+
+Over stdio (run from your app root):
+
+```bash
+claude mcp add support -- bundle exec omni_agent mcp SupportServer
+```
+
+### Claude Desktop
+
+Add the server to `claude_desktop_config.json`. Desktop does not start the process in your app root, so change to it first:
+
+```json
+{
+  "mcpServers": {
+    "support": {
+      "command": "bash",
+      "args": ["-lc", "cd /path/to/your/app && bundle exec omni_agent mcp SupportServer"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the server to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "support": {
+      "url": "http://localhost:3000/mcp/support",
+      "headers": { "Authorization": "Bearer secret" }
+    }
+  }
+}
+```
+
+### MCP Inspector
+
+[MCP Inspector](https://github.com/modelcontextprotocol/inspector) is useful for debugging. It can list tools and call them by hand:
+
+```bash
+npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp/support \
+  --transport http --header "Authorization: Bearer secret" --method tools/list
+
+npx @modelcontextprotocol/inspector --cli bundle exec omni_agent mcp SupportServer --method tools/list
+```
+
+The browser UI of the Inspector sends an `Origin` header. Add its origin to [`allowed_origins`](authentication.md#origin-checks) to use it over HTTP.