MCP Rails Implementation

Implement a complete Model Context Protocol stack in Rails, enabling your app to:

• Connect to external MCP servers as a client
• Expose itself as an MCP server for Claude Desktop, VS Code, etc.
• Manage subprocess MCP servers via Docker containers

Quick Decision Guide

What do you need?

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Your Rails App                          │
├─────────────────────────────────────────────────────────────┤
│  MCP Client Layer              │  MCP Server Layer          │
│  ┌─────────────────────┐       │  ┌─────────────────────┐   │
│  │ MCPClient           │       │  │ BaseMCPServer       │   │
│  │ - Remote HTTP/SSE   │       │  │ - JSON-RPC Handler  │   │
│  │ - Subprocess Docker │       │  │ - Tool Registry     │   │
│  │ - OAuth PKCE Flow   │       │  │ - Resource Support  │   │
│  └─────────────────────┘       │  └─────────────────────┘   │
│           │                    │            │               │
│           ▼                    │            ▼               │
│  ┌─────────────────────┐       │  ┌─────────────────────┐   │
│  │ Transport Layer     │       │  │ MCP::ServersController│  │
│  │ - HTTP Transport    │       │  │ - POST /mcp/:name/  │   │
│  │ - SSE Transport     │       │  │ - GET /mcp/:name/sse│   │
│  │ - Subprocess I/O    │       │  │ - OAuth Auth        │   │
│  └─────────────────────┘       │  └─────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Implementation Order

Phase 1: Client Core (2-3 hours)

1. Read Client Core
2. Run scaffold: ruby scripts/scaffold_mcp_client.rb
3. Implement basic JSON-RPC communication

Phase 2: Transport Layer (2-3 hours)

1. Read Transport Layer
2. Choose transport strategy: HTTP-first, SSE-first, or subprocess
3. Implement transport abstraction

Phase 3: OAuth Flow (Optional, 3-4 hours)

1. Read OAuth Flow
2. Implement PKCE discovery and token exchange
3. Add token storage to your tool configuration model

Phase 4: Docker Supervisor (Optional, 4-6 hours)

1. Read Docker Supervisor
2. Implement process lifecycle management
3. Add multi-worker coordination via database locks

Phase 5: Server Implementation (4-6 hours)

1. Read Server Implementation
2. Create BaseMCPServer DSL
3. Implement JSON-RPC controller

Key Files to Create

app/
├── services/
│   ├── mcp_client.rb                    # Core client
│   ├── mcp_client/
│   │   ├── session.rb                   # Session management
│   │   ├── oauth_flow.rb                # OAuth PKCE
│   │   └── transport/
│   │       ├── json_rpc_transport.rb    # Base interface
│   │       ├── remote_http_transport.rb # HTTP transport
│   │       ├── remote_sse_transport.rb  # SSE transport
│   │       └── subprocess_transport.rb  # Docker transport
│   └── mcp_docker_process_supervisor.rb # Container management
├── controllers/mcp/
│   └── servers_controller.rb            # MCP server endpoints
├── mcp_servers/
│   └── base_mcp_server.rb               # Server DSL
└── models/mcp/
    ├── client.rb                        # Client registration
    └── client_session.rb                # Session tracking

db/migrate/
├── create_mcp_clients.rb
└── create_mcp_client_sessions.rb

Output Checklist

When implementation is complete, verify:

• MCP client can initialize sessions and persist Mcp-Session-Id
• Client can list tools (tools/list) and call tools (tools/call)
• Transport fallback works (HTTP → SSE or vice versa)
• OAuth-enabled tools trigger PKCE flow when unauthorized
• Subprocess mode starts Docker containers with health checks
• Multi-worker coordination prevents duplicate supervisors
• Rails app exposes /mcp/:server JSON-RPC endpoint
• Optional SSE endpoint at /mcp/:server/sse streams responses
• UI resources return correct mimeType and uri formats

Common Pitfalls

1. Missing Mcp-Session-Id header: Always send session ID after initialize call
2. Ignoring transport fallback: When HTTP returns 404/405, try SSE transport
3. Treating OAuth tools like legacy tools: Must return WWW-Authenticate challenge on missing token
4. Failing to release locks for stale supervisors: Implement timeout-based cleanup
5. Embedding UI resources without correct format: Ensure mimeType and uri follow spec
6. Not handling OAuth token refresh: Tokens expire, implement refresh or re-auth flow
7. Process coordination race conditions: Use database locks for subprocess ownership

Testing Notes

Client Testing

• Initialize session and assert Mcp-Session-Id persists across requests
• Exercise both HTTP and SSE transport paths
• Simulate OAuth 401 challenge and verify token exchange flow
• Test transport fallback when primary transport fails

Server Testing

• Validate JSON-RPC success and error envelope formats
• Confirm scope enforcement on protected tools
• Test session creation, extension, and expiration
• Verify tool registration and discovery

Subprocess Testing

• Start supervisor and wait for ready state
• Kill process and verify restart or failure marking
• Simulate multi-worker contention for supervisor ownership
• Test cleanup of stale containers

References

• Client Core - JSON-RPC client implementation
• Transport Layer - HTTP, SSE, subprocess transports
• OAuth Flow - PKCE discovery and token exchange
• Docker Supervisor - Container lifecycle
• Server Implementation - Building MCP servers
• Session Management - Client sessions
• Multi-Worker Coordination - Database locks
• Host Integration - Tool configuration and app wiring
• UI Resources - Rich client rendering resources
• Testing - Test strategies and examples
• Tools and Schemas - Multi-tool server patterns
• UI Widget Pipeline - Widget template hydration