Watch

Koichi ITO 88831b46f6 Move the Documentation From README.md to the Documentation Site

Move the documentation that had grown to 3000+ lines in README.md onto https://ruby.sdk.modelcontextprotocol.io
and slim the README down to a quick start and feature overview, following the Python SDK layout:

- Add 21 server pages as the docs/_server/ collection (overview plus transports, discovery, tools, prompts, resources,
  roots, sampling, elicitation, multi round-trip results, notifications, notification subscriptions, cancellation, progress,
  ping, completions, logging, pagination, server context, configuration, and custom methods), 8 client pages as
  the docs/_client/ collection (overview, transports, lifecycle, multi round-trip results, cancellation, ping, pagination,
  and authorization), and 3 extension pages as the docs/_extensions/ collection (overview, capability extensions, and MCP Apps,
  following the Extensions Overview recommendation that SDK documentation list the supported extensions) -
  one page per topic, ordered to match the sidebar of the 2026-07-28 specification, with the client-side APIs
  (pinging, cancelling, and paginating from MCP::Client) documented under Building Clients
- Add top-level Examples and Protocol Versions pages after Installation, linking the runnable examples in examples/
  and summarizing the supported protocol versions, the era model, and client negotiation
- Render the three sections as just-the-docs collections, which list every page beneath a plain category heading in
  the sidebar with no folding, and serve every page at an extensionless URL under /server/, /client/, and /extensions/,
  matching the sibling SDK documentation sites
- Replace docs/building-servers.md and docs/building-clients.md with redirects to the new section overview pages via
  jekyll-redirect-from, redirect the previously published /installation.html to its extensionless URL, fold their content
  that was missing from README.md into the new pages, and update the Tool argument keys reference comment in lib/mcp/server.rb to
  the relocated Tools page
- Reduce README.md to the badges, a compact feature overview in the Python SDK style, installation instructions, a stdio
  server and client quick start, and a License section, using absolute URLs for the remaining repository links
  so they resolve on rubygems.org
- Adapt formatting where GitHub rendering habits break on the site: convert the numbered "three ways to define" lists into headings,
  since kramdown restarts numbering at 1 when code blocks split list items, convert GitHub-style alerts into just-the-docs callouts
  with the SEP-2260 server-to-client association note raised to a red warning, merge the duplicated Exception Reporting
  and Configuration Block Data sections into the Configuration page, and relocate the Streamable HTTP settings that were nested under
  the Logging section into the Transports page
- Refresh the migrated content against the current implementation: correct stale claims and broken samples the README carried,
  note on each session-era feature how it relates to the modern lifecycle of MCP 2026-07-28, and point spec links at the latest revision,
  keeping deliberate 2025-11-25 pins for pages the modern revision removed
- Style the site after the Rails API documentation palette (red links and accents on neutral surfaces) with matching
  light and dark color schemes, center the sidebar and content as one block, add a Previous/Next footer pager following
  the sidebar order, open external links in a new tab, and serve the MCP logo as the favicon

Every code block and heading from the previous README was verified to have a home in the new docs pages or the slimmed README before
the reduction; a few samples were corrected rather than copied, as noted above.

2026-08-21 13:24:04 +09:00

3.3 KiB

Raw Blame History

layout	title	nav_order
default	Logging	17

Logging

The MCP Ruby SDK supports structured logging through the notify_log_message method, following the MCP Logging specification.

The notifications/message notification is used for structured logging between client and server.

{: .warning }

MCP Logging (logging/setLevel and notifications/message) is deprecated as of protocol version 2026-07-28 (SEP-2577), while remaining fully supported under 2025-11-25. Use stderr or OpenTelemetry for new servers.

{: .note }

On the modern lifecycle, where logging/setLevel does not exist, the level comes per request from the io.modelcontextprotocol/logLevel _meta member: it authorizes notifications/message for that request only, delivered on the request's own response stream. A request without the member (or with an unrecognized level) receives no log messages.

Log Levels

The SDK supports 8 log levels with increasing severity:

debug - Detailed debugging information
info - General informational messages
notice - Normal but significant events
warning - Warning conditions
error - Error conditions
critical - Critical conditions
alert - Action must be taken immediately
emergency - System is unusable

How Logging Works

Client Configuration: The client sends a logging/setLevel request to configure the minimum log level
Server Filtering: The server only sends log messages at the configured level or higher severity
Notification Delivery: Log messages are sent as notifications/message to the client

For example, if the client sets the level to "error" (severity 4), the server will send messages with levels: error, critical, alert, and emergency.

For more details, see the MCP Logging specification.

Usage Example:

The client first configures the level with a logging/setLevel request:

{ "jsonrpc": "2.0", "id": 1, "method": "logging/setLevel", "params": { "level": "info" } }

The server then emits messages at each severity; only those at or above the configured level are delivered:

server = MCP::Server.new(name: "my_server")
transport = MCP::Server::Transports::StdioTransport.new(server)

server.notify_log_message(
  data: { message: "Application started successfully" },
  level: "info"
)

server.notify_log_message(
  data: { message: "Configuration file not found, using defaults" },
  level: "warning"
)

server.notify_log_message(
  data: {
    error: "Database connection failed",
    details: { host: "localhost", port: 5432 }
  },
  level: "error",
  logger: "DatabaseLogger" # Optional logger name
)

Key Features:

Server has capability logging to send log messages
Messages are only sent if a transport is configured
Messages are filtered based on the client's configured log level
If the log level hasn't been set by the client, no messages will be sent

Transport Support

stdio: Notifications are sent as JSON-RPC 2.0 messages to stdout
Streamable HTTP: Notifications are sent as JSON-RPC 2.0 messages over HTTP with streaming (chunked transfer or SSE)

3.3 KiB Raw Blame History

Logging

Log Levels

How Logging Works

Transport Support

3.3 KiB

Raw Blame History