Expose Mcp
Goal
Turn a Ruby library into an MCP-compatible service that AI agents can discover and call - with zero MCP server code, no tool definitions, and no OpenAPI specs.
What You'll See
- Create a small Ruby class with public class methods.
- Host it through Graftcode Gateway using Docker - the gateway automatically exposes an MCP endpoint.
- Connect an AI tool (Cursor or Claude Desktop) to the MCP endpoint.
- Ask the AI agent to call your methods - it discovers and invokes them through the Model Context Protocol.
Prerequisites
- Docker installed and running
- Ruby and Bundler (optional) - only if you edit files outside Docker; build and Gateway run entirely in the container
- An AI tool with MCP support - for example Cursor or Claude Desktop
Step 1. Create a project folder
mkdir ruby-ai-backend cd ruby-ai-backend
Gateway expects a gem-shaped layout: a *.gemspec in the project root (analyzed from . when you run gg .) plus a Gemfile that references it. Without them, bundle install in the Docker build fails with Could not locate Gemfile.
Create energy-service.gemspec in the project root:
# frozen_string_literal: true Gem::Specification.new do |spec| spec.name = "energy-service" spec.version = "1.0.0" spec.authors = ["Example"] spec.summary = "Energy price sample module for MCP tutorial" spec.license = "MIT" spec.files = Dir["lib/**/*.rb"] spec.require_paths = ["lib"] spec.required_ruby_version = ">= 3.2.0" end
Create Gemfile next to the gemspec:
# frozen_string_literal: true source "https://rubygems.org" gemspec
Step 2. Write a Ruby class with public methods
Create lib/energy_price_calculator.rb:
# frozen_string_literal: true class EnergyPriceCalculator def self.get_price rand(100..104) end def self.calculate_bill(kwh_used) price_per_kwh = rand(100..104).to_f kwh_used * price_per_kwh end end
No MCP-specific API - plain Ruby. Every public class method becomes a callable MCP tool once Gateway hosts the module.
Step 3. Host it with Graftcode Gateway
Create a Dockerfile in the project root:
FROM ruby:3.3-bookworm WORKDIR /usr/app COPY . /usr/app/ RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \ && curl -fsSL grft.dev/get/gg | sh && dpkg -i gg.deb && rm gg.deb \ && bundle install \ && apt-get clean && rm -rf /var/lib/apt/lists/* ENV HYPERTUBE_RUBY_RUNTIME_PATH=/usr/local/lib/libruby.so EXPOSE 80 CMD ["gg", ".", "--runtime", "ruby"]
gg (Graftcode Gateway) discovers public methods and exposes them both as Grafts for app-to-app calls and as MCP tools for AI agents. On the default --port (80) the process handles WebSocket traffic (for example ws://localhost:80/ws) and HTTP for Graftcode Vision and MCP on the same TCP port (for example http://localhost:80/GV and http://localhost:80/mcp). Gateway also listens on --httpPort (default 81) as a second HTTP stack — optional to map in Docker if you only need one host port.
Build and run the container:
docker build --no-cache --pull -t ruby-ai-backend:test . docker run -d -p 80:80 --name graftcode_mcp_demo_ruby ruby-ai-backend:test
Your Ruby service now exposes MCP automatically alongside Grafts.
Step 4. Explore the service in Graftcode Vision
Open http://localhost:80/GV.
You will see each public class method with parameters and return types. Those same methods are MCP tools agents can list and invoke.
Step 5. Connect an AI tool to the MCP endpoint
By default, MCP is available over HTTP on --port (same as WebSocket) — for this tutorial, http://localhost:80/mcp. If you expose --httpPort (default 81), http://localhost:81/mcp works too.
Cursor - add to .cursor/mcp.json (or Cursor Settings → Tools & MCP → New MCP Server):
{ "mcpServers": { "energy-service": { "url": "http://localhost:80/mcp" } } }
Claude Desktop - mcp-remote bridges stdio to the HTTP endpoint:
{ "mcpServers": { "energy-service": { "command": "npx", "args": [ "-y", "mcp-remote", "http://localhost:80/mcp" ] } } }
Restart Claude Desktop after editing its config.
Step 6. Call your methods through AI
Ask the agent something concrete, for example:
Note
"What is the current energy price?"
It should call EnergyPriceCalculator.get_price via MCP. You can also try:
Note
"Calculate the energy bill for 250 kWh"
That maps to EnergyPriceCalculator.calculate_bill(250) with no hand-authored tool definitions.
Step 7. Run with a Project Key (recommended for real-world usage)
Everything above works without any account - perfect for learning and local development. When you're ready for real-world usage, create a free account at portal.graftcode.com, set up a project, and copy its Project Key.
CMD ["gg", ".", "--runtime", "ruby", "--projectKey", "YOUR_PROJECT_KEY"]
A Project Key gives you:
- Stable MCP URL - AI tools connect to an endpoint that survives redeploys.
- Stable registry URL - RubyGems (and other managers) always resolve the same coordinates.
- Portal visibility - track gateways at gateways.graftcode.com.
- Access control - package-manager auth for Grafts and MCP consumers alike.