mcp-server

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):

1. Access to private data
2. Exposure to untrusted content
3. 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

1. Validation is multi-layered - Required args checked first, then JSON Schema validation
2. Notifications are fire-and-forget - Errors reported but don't propagate
3. Protocol version matters - Features are gated by version
4. Server context is opt-in - Detected from method signature (must include server_context: parameter)
5. 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

External Links

• MCP Ruby SDK on GitHub
• MCP Protocol Specification
• RubyDoc API Reference