mcp_server

This MCP server is a Ruby gem-based implementation designed to integrate with Rack-based Ruby applications (Rails, Sinatra, or plain Rack). It provides a pluggable MCP (Model-Context-Protocol) workflow where you define tools, prompts, and resources that can be invoked via JSON-RPC over HTTP. Tools like the example CalculatorTool show how to implement domain logic that consumes a server context (including user, permissions, and locale) and returns a structured MCP::Tool::Response. The server configuration is highly customizable: you can supply authentication logic, build a dynamic context, and provide transport/output handling. When deployed, you mount the RackApp into your app, which then handles authentication, request routing, and response construction according to the MCP protocol. If you plan to scale beyond a single process, be mindful of SSE limitations described in the README and consider enabling a single-process, multi-threaded server or disabling SSE as needed. The example also demonstrates how to wire in resources, prompts, and context-building logic to tailor the MCP experience to your domain.

Prerequisites:

• Ruby (2.6+)
• Bundler
• Optional: Docker if you plan to run via docker container

Option A: Install as a Ruby gem in your application

1. Add the gem to your Gemfile: gem 'mcp_server'
2. Install dependencies: bundle install
3. Use the MCPServer in your app (as shown in the README example) and mount MCPServer::RackApp in your Rack/Rails application.
4. Start your app as you normally would (rails server, puma, thin, etc.).

Option B: Run via Docker (using a prebuilt image)

1. Pull and run the container: docker run -i ajentik/mcp_server:latest
2. Ensure your container has access to any required resources or configuration files from your host (via volumes) and set any needed environment variables (e.g., MCP_AUTH_TOKEN).
3. Integrate with your Rack-based application by directing requests to the container or exposing the appropriate port to your application server.

Option C: Development workflow (local)

1. Ensure Ruby and Bundler are installed.
2. Clone the repository and run: bundle install
3. Create and configure your MCP server as per the Usage example in the README, then run your application in the usual development environment.

Tips and caveats:

• SSE caveat: The README notes that Server-Sent Events require in-memory stream objects, which may not work with multi-process servers. If you need SSE in a multi-process environment, consider using a single-process, multi-threaded server (e.g., Puma in single mode with multiple threads) or disable SSE by removing the Mcp-Session-Id header in the response handler.
• Authentication is optional but recommended; you can provide a custom authentication callback to validate requests.
• Context building is optional but powerful; use it to inject user data, permissions, locale, and any domain-specific data into tool execution.
• Resources, prompts, and resources_read_handler support dynamic loading and customizing how resources are read and returned.
• When integrating with Rails or Sinatra, mount MCPServer::RackApp at your desired path (e.g., /mcp) to expose the MCP API to clients.
• If you update the MCP Ruby SDK or your own tools, ensure compatibility with the Transport layer and any version-specific configuration (as noted in the README).
• For testing and development, you can exercise the example CalculatorTool and the configuration blocks to validate request handling, context propagation, and response shaping.