MCP Ruby SDK - Server Development Guide

Build Model Context Protocol servers in Ruby using the official mcp gem (maintained by Anthropic and Shopify).

Design Philosophy

Information Provider, Not Analyzer

MCP servers provide structured data; LLMs do the reasoning. Return comprehensive frameworks and raw information—let the client perform analysis and context-dependent decisions.

"The MCP server's job is to be the world's best research assistant, not a competing analyst." — Matt Adams

Context Preservation

Agents have limited context windows. Every byte returned that wasn't requested is a byte that could have held useful context. Treat context preservation as a first-class design constraint.

Principles:

Never return data that wasn't explicitly requested
Mutations are quiet—return confirmations, not data dumps
Explicit over implicit—associations only when asked
Filter large datasets before returning (10,000 rows → 5 relevant rows)

Domain-Aligned Vocabulary

Tools should speak the language of your domain, not database/CRUD terminology. Agents are collaborators in your domain process, not database clients.

Example: A visual novel asset server uses create_image, make_sprite, place_character, explore_variations, compare_images—not generate, remove_background, composite, batch_generate, get_diff.

Tool Budget Management

Too many tools overwhelm agents and increase costs. Design toolsets around clear use cases, not API endpoint mirrors.

Group related functionality intelligently
Use lazy loading for large tool sets (150K tokens → 2K via on-demand discovery)
Tool names ≤64 characters, descriptions narrow and unambiguous

Security: The Lethal Trifecta

Three capabilities that, when combined, create vulnerabilities (Simon Willison):

Access to private data
Exposure to untrusted content
External communication capabilities

Required: Explicit user consent before tool invocation, clear UI showing exposed tools, alerts when tool descriptions change.

Domain Components

Component	Purpose	Reference
Tools	Define callable functions with input/output schemas	`references/tools.md`
Prompts	Template-based message generators	`references/prompts.md`
Resources	Static and dynamic file/data registration	`references/resources.md`
Server	Core server initialization and configuration	`references/server.md`
Transport	STDIO and HTTP transport options	`references/transport.md`
Gotchas	Tricky behaviors and error handling	`references/gotchas.md`

Key Concepts

Concept	Purpose
`MCP::Tool`	Base class for defining callable tools
`MCP::Prompt`	Base class for prompt templates
`MCP::Resource`	Static resource registration
`MCP::ResourceTemplate`	Dynamic URI-based resources
`server_context`	Request-scoped data passed to handlers
`MCP::Tool::Response`	Structured tool return value

Tool Definition Patterns

Pattern	Use Case
Class-based (`< MCP::Tool`)	Reusable tools with complex logic
Block-based (`MCP::Tool.define`)	Inline, simple tools
Dynamic (`server.define_tool`)	Runtime tool registration

Transport Decision Tree

What environment?
├── CLI tool / Local server
│   └── Use STDIO transport
└── Web server / Production
    └── Need sessions and notifications?
        ├── YES → Use Streamable HTTP (stateful)
        └── NO → Use Streamable HTTP (stateless)

Quick Comparison

Transport	Sessions	Notifications	Use For
STDIO	N/A	Yes	CLI tools, local dev
HTTP (stateful)	Yes	Yes	Web apps, long-lived connections
HTTP (stateless)	No	No	Simple request/response APIs

Protocol Version Features

Feature	Minimum Version
`description`	2025-11-25
`instructions`	2025-03-26
`annotations`	2025-03-26
`output_schema`	2025-03-26

Best Practices

Do

Use tool_name for namespaced classes to avoid conflicts
Use additionalProperties: false for strict schema validation
Use mutex for shared state in HTTP transport (thread safety)
Return error responses for business errors (Response.new([...], error: true))
Check protocol version before using newer features
Use server_context for request-scoped data (user_id, env)

Don't

Don't use $ref in schemas (raises ArgumentError, inline only)
Don't assume extra args are rejected (additionalProperties defaults to allowing extras)
Don't use rpc. prefix (reserved for protocol methods)
Don't send notifications in stateless mode (raises RuntimeError)
Don't rely on validation order (required args checked before JSON Schema)

Anti-Patterns Quick List

Anti-Pattern	Solution
Missing `additionalProperties: false`	Add to schema for strict validation
Using `$ref` in schemas	Inline all definitions
Notifications in stateless mode	Use stateful transport or skip notifications
Hardcoded server_context	Pass dynamically based on request
Ignoring protocol version	Check version before using gated features
Blocking in tool handlers	Use async patterns for long operations

Key Points

Validation is multi-layered - Required args checked first, then JSON Schema validation
Notifications are fire-and-forget - Errors reported but don't propagate
Protocol version matters - Features are gated by version
Server context is opt-in - Detected from method signature (must include server_context: parameter)
Schemas are immutable - Validated at class load time, not runtime

Additional Resources

Reference Files

For detailed DSL syntax by domain:

references/tools.md - Tool definition, responses, schemas, annotations
references/prompts.md - Prompt definition, arguments, content types
references/resources.md - Resource registration, templates, read handlers
references/server.md - Server initialization, configuration, custom methods
references/transport.md - Transport config, protocol methods, sessions
references/gotchas.md - Tricky behaviors, error handling, edge cases

Example Files

Working examples in examples/:

examples/stdio_server.rb - Complete STDIO server with tools, prompts, resources
examples/http_server.rb - HTTP server with Rack and logging
examples/rails_integration.rb - Rails controller, routes, and initializer
examples/file_manager_tool.rb - Sandboxed file operations with security patterns
examples/dynamic_tools.rb - Runtime tool registration with notifications
examples/http_client.rb - HTTP client connecting to MCP server
examples/streaming_client.rb - SSE streaming client for real-time notifications

MCP Server (Ruby)