Building Uscreen’s remote, multi-tenant MCP server inside a Rails app

Evil Martians moved Uscreen's Model Context Protocol server from a locally installed NPM package into Uscreen's existing Rails application, letting creators connect an AI client by pasting a URL, signing in, and approving access instead of installing software and managing API keys. The remote, multi-tenant server exposes 57 tools that call the same Rails models and business logic as the product, keeps every request scoped to the creator's own Account and approved permissions, and previews the effect of destructive tools by default, such as how many subscribers a deleted tag would affect. The implementation pairs an OAuth server for sign-in with a library for account scoping, and Evil Martians says the same approach works for any Rails product that wants to give users AI access to their accounts.

Building Uscreen’s remote, multi-tenant MCP server inside a Rails app Uscreen https://www.uscreen.tv , the leading all-in-one membership platform for video creators and entrepreneurs, came to Evil Martians with a working Model Context Protocol MCP server already tested by early adopters. To use it, a creator installed an NPM package that ran the server on their computer, entered an API key, and plugged it into the AI client of their choice. It worked, but it took a lot of setup. So, to make creators’ lives easier, Evil Martians moved the server into Uscreen’s Rails application. Now, all a creator needs to do is add the Uscreen MCP URL to their AI client, sign in, and approve access. This post covers how that implementation works: authenticating a creator, keeping requests inside the right account, defining tools around existing Rails models, and previewing destructive changes. Let’s take Fit with Coco https://fitwithcoco.com/ as an example; it’s a fitness membership with hundreds of Pilates, strength, and cardio workouts, multi-week challenges, and a seven-day free trial. Now, imagine running all of that through an admin panel. The users with programs like this can be expected to know the perfect plank, but not necessarily their way around Vim. The panel handles individual edits and some bulk actions, but plenty of tasks span many records and can turn into an evening of scrolling, filtering, and ticking checkboxes. For example: - Updating descriptions and tags for every workout in a six-week challenge. - Finding workouts with the most watch time in a week and comparing monthly recurring revenue with last month. - Listing subscriptions scheduled to cancel at the end of the billing period and free trials ending this week, grouped by plan. These were the kinds of tasks we wanted creators to describe once rather than complete item by item . And thankfully, MCP gives an AI client a way to request the necessary application operations. - Uscreen creators can connect an AI client to their account by pasting a URL, signing in, and approving access. They don’t install anything or manage API keys. - We built the MCP server into Uscreen’s existing Rails application. Its 57 tools use the same models and business logic as the product, and new tools ship with regular deploys. - Every request stays inside the creator’s own account and the permissions they approved. - Destructive tools preview their effect by default, such as how many subscribers a deleted tag would affect. - This same approach works for any Rails product that wants to give its users AI access to their accounts. Table of contents : The original server ran locally on each creator’s computer. Creators had to install and configure it, and every new tool came with a package update. Hosting the server removed that work on its own. Where to host was a separate decision. The local server talked to Uscreen through its public API, so it could only do what the API already offered. A new tool often meant adding a public endpoint first, and every public endpoint is a contract Uscreen has to keep stable for all the integrations built on it. Putting the server inside the Rails application removed that step: Inside Rails, a tool is one more entry point to the application, like a controller. It calls the same models and services as the API and the admin panel, and it ships with the application instead of waiting for a new endpoint and a package release. A remote server also takes on new responsibilities. It has to know who is behind each request the creator or a team member with admin access , which Account they’re acting for, and what they’re allowed to do. Uscreen is multi-tenant: each creator works in a space of their own, an Account , that holds their videos, subscribers, and everything else they’ve built. Every request had to stay inside the right one. That meant two pieces of infrastructure: an OAuth server to sign people in and a library to handle MCP requests. For the MCP library, we had two options at the time: the official mcp gem https://github.com/modelcontextprotocol/ruby-sdk and fast-mcp https://github.com/yjacquin/fast-mcp . The official gem won on three counts: - Transport. It supported Streamable HTTP, the standard transport for remote MCP servers, with a stateless mode, so any application instance can handle any request. fast-mcp only offered the older HTTP+SSE transport, which keeps each client’s stream in one process’s memory. - Per-request context. The official gem passes a server context with the Account, user, and token into every tool call. fast-mcp tools only receive the request headers, so each tool would have to look up the token again. - Maintenance. The official gem is maintained by the MCP project alongside the specification and was updated often. fast-mcp hadn’t had a release since September 2025. For authentication, the MCP specification builds on OAuth 2.1, and the Rails ecosystem has a battle-tested component for that: Doorkeeper https://github.com/doorkeeper-gem/doorkeeper . Uscreen had even used it before, for an older version of its API, so bringing it back meant reusing the OAuth tables already in the schema rather than starting from scratch: ~/Gemfile gem "doorkeeper" gem "mcp", "~ 1.1.0" The official gem gives each tool a MCP::Tool class with a name, a description, an input schema, and a call method. Every Uscreen tool inherits from one more layer, Mcp::ApplicationTool , the same way Rails models inherit from ApplicationRecord : ~/app/lib/mcp/application tool.rb module Mcp class ApplicationTool < MCP::Tool include ActiveSupport::Rescuable rescue from ActiveRecord::RecordNotFound do |error| failure response " {error.model.underscore} not found" end class << self def description from template locals namespace = module parent.name.delete prefix "Mcp::Tools" .delete prefix "::" .underscore template = Rails.root.join "app/lib/mcp/descriptions", namespace, " {tool name}.txt.erb" .read description ERB.new template, trim mode: "-" .result with hash locals end def call server context:, args verify scope server context perform server context: server context, args rescue = error rescue with handler error || raise end def respond with resource, options body = ActiveModelSerializers::SerializableResource.new resource, options .as json MCP::Tool::Response.new { type: "text", text: body.to json } end def failure response error code body = { error: error code, message: I18n.t "mcp.errors. {error code}" } MCP::Tool::Response.new { type: "text", text: body.to json } , error: true end Scope checks: requires scope, verify scope , ... end end end With that in place, a tool’s perform only contains its own logic: python ~/app/lib/mcp/tools/cms/videos/get tool.rb def perform server context:, video id: video = server context :account .videos.not deleted.find video id respond with video end respond with finds the model’s serializer and wraps the result in an MCP response. A missing ID raises ActiveRecord::RecordNotFound , and the base class turns it into a video not found error. The same happens when the ID belongs to another Account, because the lookup starts from the Account in server context . server context carries the Account, user, and scopes from the access token; we’ll show how it gets there in Authorization in MCP 101 authorization-in-mcp-101 . Each tool tells the model what arguments it takes, when to use it, and how it behaves. Here’s the rest of videos get , whose perform we saw above: ~/app/lib/mcp/tools/cms/videos/get tool.rb class GetTool < Mcp::ApplicationTool tool name "videos get" description from template annotations title: "Get video", read only hint: true, destructive hint: false, idempotent hint: false, open world hint: false input schema properties: { video id: { type: "integer", minimum: 1, description: "Internal video id. Get it from videos list response data .id ." } }, required: "video id" requires scope Mcp::Scopes::CMS READ ... end The input schema declares the arguments a tool accepts. Its descriptions can also tell the model where those arguments should come from: here, video id points the caller to videos list rather than asking it to infer an ID from a title. The tool description answers a different question: when should this tool be used? We keep those descriptions in ERB templates, separate from the Ruby implementation, so they can distinguish related operations such as fetching one video, listing videos, or fetching a collection. Here’s the full videos get description: <% ~/app/lib/mcp/descriptions/cms/videos/videos get.txt.erb % <purpose Fetch one standalone video by id. Returns the same field set as a videos list row plus resource attachments — the creator-uploaded files PDFs, images, audio, etc. linked to the video. </purpose <returns A single video object: id, title, description, duration seconds , tags, status, custom filters, category ids, collection ids, published at, thumbnail url, resource attachments. status is one of 'published' | 'scheduled' | 'unpublished'. custom filters is a list of {filter id, filter title, option id, option title} entries — empty when the video has no filters set. resource attachments is a list of {id, title, filename, content type, download url} entries — empty when no files are attached. download url is a presigned S3 URL with a 6-hour TTL. </returns <use when - Drill-down after videos list : "show me everything about video id=42" - "What files are attached to this video?" resource attachments - Auditing a specific video's metadata, tags, custom filters, or category/collection membership </use when <do not use when - For LISTING multiple videos — call videos list instead - For name/slug lookup — videos get takes the integer id only; resolve name → id via videos list first - For collections / courses / series — use collections get - For categories — use categories get </do not use when Why so much text? The beta version of the server had no tool descriptions at all. When we moved it into Rails, we wrote one for every tool and gave them all the same structure: <purpose , <returns , <use when , and <do not use when . AI agents understand a request and act on it more reliably when it’s structured up front, so each block is wrapped in pseudo-XML tags. The <do not use when block, in particular, keeps the model from reaching for a neighboring tool. Most of the remaining text answers a specific mistake a model would make. On Uscreen, courses and series are collections, not videos, so a model asked about “the 30-day challenge” might reach for videos get . The <do not use when block instead sends it to collections get . Annotations such as read only hint and destructive hint , like the ones on videos get above, describe a tool’s behavior to the client; they don’t enforce permissions or require human approval. For destructive operations, we make the default behavior cautious as well. Deleting a tag attached to three subscribers is different from deleting one attached to three thousand, so our delete member tag tool previews its effect when dry run is omitted: python ~/app/lib/mcp/tools/crm/tags/delete tool.rb def perform server context:, tag id:, dry run: true tag = server context :account .custom user tags.find by id: tag id return failure response "member tag not found" if tag.nil? name = tag.name members untagged = tag.users count referenced by automations = tag.referenced by automations? return dry run response tag id, name, members untagged, referenced by automations if dry run tag.destroy success response tag id, name, members untagged, referenced by automations end ... The preview returns the tag’s name, subscriber count, and whether automations reference it. The tool’s description explains why that matters: deleting a tag strips it from every member who has it, and each removal can enroll that member in a published tag removed automation, one run per member. So, the description tells the model to check members untagged in the preview before passing dry run: false . Passing dry run: false proceeds to deletion. This is a safer default; it is not an approval mechanism. A caller with the required permission can send dry run: false on its first call. A preview can also become stale if the underlying data changes before a later deletion. Many tools stay close to what Uscreen’s REST API already offers, but inviting customers shows where MCP goes further. Say the coach behind Fit with Coco wants to invite a dozen people from a weekend studio class and jotted down a note about each: “recovering from a knee injury,” “training for a first half marathon,” “only has 20 minutes in the morning.” The AI client fetches the store’s invite template with get invite email template and writes each invitation from that person’s note, so one points to low-impact Pilates and another to strength workouts for runners. The template’s placeholders stay in place, and the coach sees who will get an email before invite customer sends anything. The same call can grant a subscription plan, bundles, and tags. So, the personalization is not an arbitrary thing: the creator notes determine what each email says, the template decides its shape, and nothing is sent out without the creator’s confirmation. The REST API can create a customer, but writing the email is left to whoever calls it. Inside Rails, the tool reuses the same invitation model as the admin panel: python ~/app/lib/mcp/tools/crm/users/invite customer tool.rb def perform server context:, email:, subject: nil, body: nil, grants ... Users::Invite.call email: email, subject: subject, body: body, user: server context :user , grants ... end Users::Invite is the same code the admin panel uses to invite people, so an agent’s invitations count against the same quota as a creator’s. An agent that can email customers and delete tags on a creator’s behalf needs firm limits. Let’s take a deeper look at the backend implementation, especially the parts that keep it secure. A remote server has to answer two questions on every request: who is calling, and which Account are they acting for? Uscreen answers both with OAuth, so a creator never has to copy an API key. When a creator adds Uscreen’s MCP server URL to an AI client, the client finds everything else on its own. Protected resource metadata https://datatracker.ietf.org/doc/html/rfc9728 points it to the authorization server, authorization server metadata https://datatracker.ietf.org/doc/html/rfc8414 lists the registration, authorization, and token endpoints, and dynamic client registration https://datatracker.ietf.org/doc/html/rfc7591 gives it a client id without the creator registering an application by hand. Uscreen’s storefront and admin hosts are separate, so the metadata sends the client to the admin host, where login and consent happen. Registration identifies the client, but it doesn’t grant access to an Account. That happens when the creator signs in and approves the client. Doorkeeper connects that step to Uscreen’s existing login. We enable authorization-code and refresh-token grants, require PKCE, and define the permissions a client can request: ~/config/initializers/doorkeeper.rb Doorkeeper.configure do orm :active record resource owner authenticator do current user || redirect to creator sign in path redirect url: request.fullpath end grant flows %w authorization code refresh token force pkce use refresh token No default scopes: the client has to ask for rights out loud. optional scopes "content analytics.read", "finance analytics.read", "crm.read", "cms.read", "products.read", "cms.write", "crm.write" custom access token attributes %i account id audience force ssl in redirect uri do |uri| uri.scheme == "http" && %w localhost 127.0.0.1 ::1 .include? uri.host end end The custom access token attributes line adds account id and audience to the grant and access-token records. The Account identifies the tenant; the audience identifies the MCP endpoint the token is intended for. We derive the Account from the authenticated user: ~/app/controllers/oauth/authorizations controller.rb module OAuth class AuthorizationsController < Doorkeeper::AuthorizationsController private def pre auth params super.merge account id: current resource owner.account.id, audience: params :resource .presence || " {request.base url}/mcp" end end end The order of the merge matters. account id follows super , so it overwrites any client-supplied value. A caller cannot select another Account by adding an identifier to the authorization request. The account comes from the user who signed in and approved access. The audience ties the token to an MCP endpoint. The request handler checks it again when the token is used. Once connected, the client sends its access token in the Authorization header. Before invoking the MCP SDK, we check the token, its audience, the Account, and the user’s membership: ~/app/controllers/mcp/streamable controller.rb def authenticate mcp request token str = request.authorization.to s /\ABearer\s+ .+ \z/i, 1 return unauthorized "invalid request", "Missing access token" unless token str token = Doorkeeper::AccessToken.by token token str return unauthorized "invalid token", "Invalid or expired token" unless token&.accessible? return unauthorized "invalid token", "Wrong audience" unless token.audience == expected audience account = Account.active.find by id: token.account id return unauthorized "invalid token", "Account unavailable" unless account user = account.admins.not deleted.find by id: token.resource owner id return unauthorized "invalid token", "User unavailable" unless user @mcp token = token @mcp account = account @mcp user = user end The Account must still be active, and the user must still be one of its administrators. A valid token alone is not enough to retain access after that membership has been removed. After authentication, the controller builds a new MCP server for the request and passes it the Account, user, token, and scopes: ~/app/controllers/mcp/streamable controller.rb def handle server = MCP::Server.new name: NAME, version: VERSION, tools: available tools, server context: { token: @mcp token, account: @mcp account, user: @mcp user, scopes: @mcp token.scopes.to a } transport = MCP::Server::Transports::StreamableHTTPTransport.new server, stateless: true, enable json response: true, dns rebinding protection: false ... end The SDK handles the MCP messages. Tool execution receives the authenticated context through server context . We use the transport in stateless mode so a request does not depend on an earlier MCP request reaching the same application instance. Uscreen still stores tokens and business data; “stateless” here refers to MCP session state. Because each request gets its own server, we can only advertise the tools the token’s scopes allow: ~/app/controllers/mcp/streamable controller.rb def available tools scopes = @mcp token.scopes.to a Mcp::ToolRegistry.tools.select { |tool| tool.available to? scopes } end Therefore, a token without cms.write does not see write tools in tools/list . But hiding a tool is not the security boundary: permission is checked again when the tool is called. Both checks live in ApplicationTool : ~/app/lib/mcp/application tool.rb module Mcp class ApplicationTool < MCP::Tool class InsufficientScopeError < StandardError; end class attribute :required scope, instance accessor: false class attribute :scope check skipped, instance accessor: false, default: false class << self def requires scope scope self.required scope = scope.to s end def skip scope check self.scope check skipped = true end def available to? scopes return true if scope check skipped required scope.present? && Array scopes .include? required scope end ... private def verify scope server context return if scope check skipped raise " {name} did not declare requires scope" if required scope.nil? scopes = Array server context :scopes return if scopes.include? required scope raise InsufficientScopeError, "Tool requires scope: {required scope}" end end end end Each tool declares its scope with requires scope and implements perform . The base class’s call , shown earlier, runs verify scope before perform . A tool that needs no scope, like whoami , opts out explicitly with skip scope check . A tool that does neither is hidden from the list and raises an error if called, so a forgotten declaration fails closed. Creators no longer need to install and maintain a local server. They connect through a URL, sign in, and approve access. New tools ship with regular Rails deploys instead of a package update, and they work directly with Uscreen’s models while each request stays tied to the authenticated Account and its permissions. If your users already manage their data in a Rails app, most of the work is already done. Here’s what we took away from the Uscreen project: - Adding MCP isn’t the hard part. The official mcp gem handles the protocol, and the first read-only version of Uscreen’s server shipped about two weeks after Doorkeeper came back into the app. The time goes into details: which Account a token belongs to, what a tool returns for a missing ID, how a destructive call previews its effect. - Authorization is the core of the work. A token has to stay bound to one Account and one endpoint, and access has to end as soon as someone loses their admin role. Cover every failure path with tests: Uscreen’s suite has a request spec for each way a token can be rejected, including a wrong audience and a demoted admin. - Tool descriptions are written for the model. The model picks tools by their descriptions, so spell out when not to use a tool and which arguments can wipe data. - As usual, Rails already had most of what we needed. The MCP endpoint is an ordinary controller with a before action . Doorkeeper handles OAuth, Rack::Attack https://github.com/rack/rack-attack throttles both /mcp and the open client registration endpoint, and a parameter filter keeps tool arguments with personal data out of the logs. Inside the tools, rescue from , serializers, and I18n keep perform short, and inviting a customer is a call to the code the admin panel already uses. Building inside Rails means the MCP server inherits the rules the product already enforces instead of reimplementing them behind an API.