mcp-rails

The mcp-rails skill provides a robust architectural framework for integrating the Model Context Protocol (MCP) into Ruby on Rails applications. It is designed for developers building AI agents, tool-integrated applications, and LLM-powered services that require standardized communication with Claude Desktop, VS Code, or custom agent environments. This skill abstracts the complexities of JSON-RPC 2.0 communication, transport layer handling, and authentication, enabling your application to act as both a client and a server within the MCP ecosystem.

• Full MCP Server implementation with tool registration, resource support, and JSON-RPC controller logic.

• Sophisticated MCP Client capable of connecting to remote tools via HTTP, SSE streaming, or local Docker-based subprocesses.

• Native support for OAuth 2.1 PKCE flows, ensuring secure interactions with protected MCP tools and services.

• Advanced Docker supervisor for managing subprocess MCP servers, featuring health checks, multi-worker coordination, and database-backed session management.

• Built-in transport fallback logic that intelligently switches between HTTP and SSE strategies based on availability and environment constraints.

• UI Widget pipeline to easily embed visual elements and interactive components within tool responses.

• Ensure your environment meets the core requirements: Rails 7+, Ruby 3.2+, and PostgreSQL for robust session and lock management.

• Utilize the scaffold generator to quickly boot up client configurations and establish standard JSON-RPC communication paths.

• Implement transport strategies (HTTP-first vs SSE-first) according to your deployment latency needs and network topology.

• Use the provided Docker supervisor for isolating external MCP tools, which helps prevent resource contention and improves system reliability.

• For authentication-heavy tools, ensure your database stores tokens securely and that your application handles the WWW-Authenticate 401 challenge sequence effectively.

• The skill includes detailed references for every layer of the protocol, from the Client Core to complex subprocess management, ensuring that you can customize the stack to suit specific agentic workflows or enterprise-grade integrations.