| name | mcp-server |
| description | Ruby MCP server development — tools, prompts, resources, transport, the mcp gem, LLM tool integrations. |
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
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, annotationsreferences/prompts.md - Prompt definition, arguments, content typesreferences/resources.md - Resource registration, templates, read handlersreferences/server.md - Server initialization, configuration, custom methodsreferences/transport.md - Transport config, protocol methods, sessionsreferences/gotchas.md - Tricky behaviors, error handling, edge cases
Example Files
Working examples in examples/:
examples/stdio_server.rb - Complete STDIO server with tools, prompts, resourcesexamples/http_server.rb - HTTP server with Rack and loggingexamples/rails_integration.rb - Rails controller, routes, and initializerexamples/file_manager_tool.rb - Sandboxed file operations with security patternsexamples/dynamic_tools.rb - Runtime tool registration with notificationsexamples/http_client.rb - HTTP client connecting to MCP serverexamples/streaming_client.rb - SSE streaming client for real-time notifications
External Links
