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.

- Streamable HTTP is the built-in transport, with session management, resumability, and MCP 2025-11-25 compliance
- Class-based tools viaVectorMCP::Tool, plus the original block-basedregister_toolAPI
- Rack and Rails mounting throughserver.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

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"] }

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 inconfig/routes.rb:

For ActiveRecord-backed tools, opt intoVectorMCP::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

Seedocs/rails-setup-guide.mdfor a full setup guide.

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

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

server.register_prompt( name: "code_review", description: "Reviews code for best practices", arguments: [ { name: "language", description: "Programming language", required: true }, { name: "code", description: "Code to review", required: true } ] ) do |args| { messages: [{ role: "user", content: { type: "text", text: "Review this #{args["language"]} code:\n\n#{args["code"]}" } }] } end

VectorMCP::Toolalso supportstype: :dateandtype: :datetime, which are validated as strings in JSON Schema and coerced toDateandTimebefore#callruns.

Handlers that take a second argument receive the per-request invocation, which exposes session identity, the request's headers/params, and the authenticated user in one place:

server.register_tool( name: "whoami", description: "Reports the caller's identity", input_schema: { type: "object", properties: {} } ) do |_args, invocation| { session: invocation.id, user: invocation.user, api_key_header: invocation.request_header("X-API-Key") } end

Resource handlers get the same invocation as their second argument (it also answers the familiaruser/authenticated?/can?queries, so handlers written against the older security-context argument keep working unchanged).

VectorMCP keeps security opt-in, but the primitives are built in:

server.enable_authentication!( strategy: :api_key, keys: [ENV.fetch("MCP_API_KEY")], rate_limit: { max_attempts: 10, window_seconds: 60 } ) server.enable_authorization! do authorize_tools do |user, _action, tool| user[:role] == "admin" || !tool.name.start_with?("admin_") end end

server.enable_authentication!(strategy: :custom) do |request| api_key = request[:headers]["X-API-Key"] user = User.find_by(api_key: api_key) user ? { user_id: user.id, role: user.role } : false end

When authentication is enabled, VectorMCP applies it centrally to built-in and custom request/notification handlers. Onlyinitialize,ping, and theinitializednotification are public; HTTP GET streams and DELETE session requests also require credentials.

For public deployments, enable authentication failure limiting withrate_limit: true(10 attempts per 60 seconds by default), or providemax_attempts,window_seconds, andmax_entries. Repeated failures are tracked by client IP and a one-way credential fingerprint; blocked requests return HTTP429, JSON-RPC-32029, andRetry-After. The limiter is in-process, so multi-process or distributed deployments should also enforce a shared limit at the proxy or gateway. Generate API keys with at least 256 bits of entropy—for example,ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'—and load them from a secret manager or environment variable.

For MCP clients that speak OAuth 2.1 (e.g. Claude Desktop), pass aresource_metadata_url:to turn on RFC 9728 discovery. Unauthenticated requests to/mcpreturn401with aWWW-Authenticateheader pointing at the configured metadata document, and the client drives the rest of the OAuth dance automatically. Seedocs/oauth_resource_server.mdfor the feature reference anddocs/rails_oauth_integration.mdfor a full Rails + Doorkeeper recipe.

Seesecurity/README.mdfor the full security guide.

anonymizer = VectorMCP::Middleware::Anonymizer.new( store: VectorMCP::TokenStore.new, field_rules: [ { pattern: /email/i, prefix: "EMAIL" }, { pattern: /\bssn\b/i, prefix: "SSN" } ] ) anonymizer.install_on(server)

- VectorMCP ships with streamable HTTP as its built-in transport
- POST /mcpaccepts a single JSON-RPC request, notification, or response; batch arrays are rejected
- GET /mcpopens an SSE stream for server-initiated messages
- DELETE /mcpterminates the session
- The server advertises MCP protocol2025-11-25and accepts2025-03-26and2024-11-05headers for compatibility
- Default allowed origins are restricted to localhost and loopback addresses
- POST bodies are capped at 16 MiB by default; configuremax_body_bytes:onrunorrack_appwhen needed
- For mounted Rack apps, configure the same limit in the fronting web server or reverse proxy so requests are rejected before Rack buffering

curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

- Roots viaregister_rootandregister_root_from_path
- Image resources and image-aware tools/prompts
- Structured logging with component loggers
- Server-initiated sampling with streaming/tool-call support
- Middleware-driven request shaping and observability

- CHANGELOG.md
- examples/
- docs/rails-setup-guide.md
- docs/rails_oauth_integration.md
- docs/oauth_resource_server.md
- docs/streamable-http-spec-compliance.md
- security/README.md
- MCP Specification

Bug reports and pull requests are welcome onGitHub.

Available as open source under theMIT License.

A TypeScript agent that integrates MCP servers with Ollama, allowing AI models to use various tools through a unified interface.