Documentation / Mcp / Export Mcp Feature

Porting Playbook

Goal

Recreate the MCP feature in another Rails project without copying this repository's marketplace or CRM business logic.

Pre-Flight Decisions

Answer these before you port anything:

  1. Will the target app have one MCP server or two?
  2. Is the target app multi-tenant?
  3. What is the tenant root: Organization, Account, Workspace, or something else?
  4. What is the domain root for tool queries: marketplace, project, workspace, or direct model access?
  5. Do you need token CRUD in the web UI, or is token management API-only?
  6. Will the target app support mutation tools, or only read tools at first?

Phase 1: Bring Over The Shared Runtime

Add the mcp gem and create the Mcp namespace.

Port these first:

  • base Rack app
  • token model
  • activity log model
  • shared concerns

At the end of this phase, the target app should have the primitives needed to authenticate tokens and log tool calls.

Phase 2: Define The Scope Object

In this repository the scope object is Mcp::OrganizationContext.

Recreate that object for the target app and make it answer the minimum data every tool needs.

Typical context fields:

  • organization or equivalent tenant
  • domain_root such as marketplace, if useful
  • token

If the target app is single-tenant, replace the tenant field with an app-level or environment-level object and drop the tenant-specific authorization checks.

Phase 3: Wire The Rack Endpoint

Add a Rack subclass that answers three questions:

  1. Is the token authorized for this endpoint?
  2. How do I build the correct server for this token?
  3. What request-local flags do I need before and after dispatch?

In this repository, the org endpoint also toggles Current.mcp_request so downstream write activity can be tagged as MCP-originated.

Phase 4: Port The Builder And Base Tool

Bring over the org server builder and base tool.

Adapt these pieces carefully:

  • tool namespaces
  • context accessor names
  • domain and action permission keys
  • activity logging hooks

Once this is done, the target project can serve tools/list even before the business tools exist.

Phase 5: Rebuild Tool Domains One By One

Do not port all business tools at once. Start with one read-only domain.

Recommended order:

  1. one list tool
  2. one get tool
  3. one safe update tool
  4. one create tool if needed

Use the pattern from this repository:

  • each tool handles one action
  • each tool has a precise tool_name
  • each tool declares mcp_domain and mcp_action
  • each tool starts from a scoped association rather than an unscoped model

Phase 6: Add Token Management

If the target app needs human-operated token lifecycle management, add:

  • controller for listing tokens
  • controller for create, update, revoke, regenerate
  • permission toggle form
  • activity log view

The UI is optional. The runtime works without it, but production teams usually need a safe place to issue and rotate tokens.

Phase 7: Add The Admin MCP Only If It Solves A Real Problem

The admin MCP is worth exporting when the target app needs:

  • platform-wide analytics
  • staff-only cross-tenant support tools
  • internal CRM or operations automation

If the target app does not need cross-tenant tooling, skip the admin MCP completely.

Phase 8: Test Before Adding More Tool Surface

Before the tool catalog grows, validate these scenarios:

  1. valid token can call tools/list
  2. revoked token gets 401
  3. token only sees permitted tools
  4. tool call creates an activity log row
  5. tool cannot cross tenant boundaries
  6. rate limit returns 429 after threshold

Copy Matrix

Copy almost directly

  • Mcp::BaseRackApp
  • Mcp::Tools::Concerns::Formattable
  • Mcp::Tools::Concerns::Listable
  • Mcp::Tools::Concerns::ToolMetadata

Copy, then adapt to the target domain

  • Mcp::Token
  • Mcp::ActivityLog
  • Mcp::OrganizationContext
  • Mcp::RackApp
  • Mcp::BaseTool
  • Mcp::ServerBuilder
  • routes and controllers

Rebuild from scratch

  • tool classes that depend on marketplace, leads, reviews, docs, or CRM
  • org/admin policies tied to this repository's membership model
  • the exact token settings pages if the target app has a different design system

Suggested Rollout In Another Project

Smallest viable export

  • one org MCP endpoint
  • token model
  • activity log
  • one domain with read-only tools

Full parity export

  • org MCP
  • admin MCP
  • token UI
  • activity viewer
  • multiple permission groups
  • read and mutation tools

Common Adaptation Points

No marketplace model

Replace organization.marketplace with your own domain root, or have tools query directly from organization.

No multi-tenancy

Replace organization resolution with app-level authorization and remove org associations from tokens and logs.

No Current model

You can omit Current.mcp_request entirely at first. The MCP runtime does not require it. It is only used here for downstream audit tagging.

Non-admin authorization model

Replace membership-based policies with your own admin or role checks. The MCP runtime does not care how the UI authorizes token creation.