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