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

Key Concepts

Tool Definition Patterns

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

Protocol Version Features

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

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