VectorMCP

VectorMCP is a Ruby implementation of the Model Context Protocol (MCP) server-side specification. It gives you a framework for exposing tools, resources, prompts, roots, sampling, middleware, and security over the MCP streamable HTTP transport.

Highlights

• Streamable HTTP is the built-in transport, with session management, resumability, and MCP 2025-11-25 compliance
• Class-based tools via VectorMCP::Tool, plus the original block-based register_tool API
• Rack and Rails mounting through server.rack_app
• Opt-in authentication and authorization, structured logging, and middleware hooks
• Request-scoped identity: every request is dispatched through its own invocation, so concurrent requests on one session can never observe each other's headers or auth
• Image-aware tools/resources/prompts, roots, and server-initiated sampling
• Token-based field anonymization middleware to keep sensitive values out of LLM context

Requirements

• Ruby 3.2+

Installation

gem install vector_mcp

gem "vector_mcp"

Quick Start

require "vector_mcp"

class Greet < VectorMCP::Tool
  description "Say hello to someone"
  param :name, type: :string, desc: "Name to greet", required: true

  def call(args, _session)
    "Hello, #{args["name"]}!"
  end
end

server = VectorMCP::Server.new(name: "MyApp", version: "1.0.0")
server.register(Greet)
server.run(port: 8080)

The class-based DSL is optional. The existing block-based API still works:

server.register_tool(
  name: "echo",
  description: "Echo back the supplied text",
  input_schema: {
    type: "object",
    properties: { text: { type: "string" } },
    required: ["text"]
  }
) { |args| args["text"] }

Rack and Rails

VectorMCP can run as a standalone HTTP server or be mounted inside an existing Rack app:

require "vector_mcp"

server = VectorMCP::Server.new(name: "MyApp", version: "1.0.0")
server.register(Greet)

MCP_APP = server.rack_app

In Rails, mount it in config/routes.rb:

mount MCP_APP => "/mcp"

For ActiveRecord-backed tools, opt into VectorMCP::Rails::Tool:

require "vector_mcp/rails/tool"

class FindUser < VectorMCP::Rails::Tool
  description "Find a user by id"
  param :id, type: :integer, required: true

  def call(args, _session)
    user = find!(User, args[:id])
    { id: user.id, email: user.email }
  end
end

See docs/rails-setup-guide.md for a full setup guide.

Tools, Resources, and Prompts

Expose callable tools:

server.register_tool(
  name: "calculate",
  description: "Performs basic math",
  input_schema: {
    type: "object",
    properties: {
      operation: { type: "string", enum: ["add", "subtract", "multiply"] },
      a: { type: "number" },
      b: { type: "number" }
    },
    required: ["operation", "a", "b"]
  }
) do |args|
  case args["operation"]
  when "add" then args["a"] + args["b"]
  when "subtract" then args["a"] - args["b"]
  when "multiply" then args["a"] * args["b"]
  end
end

Expose readable resources:

server.register_resource(
  uri: "file://config.json",
  name: "App Configuration",
  description: "Current application settings"
) { File.read("config.json") }

Define prompt templates: