mcp-startup-boilerplate

MCP Startup Boilerplate v0.0.1

A robust, free, ready-to-use Rails boilerplate for building AI-powered applications that integrate seamlessly with Claude AI using the Model Context Protocol (MCP). This boilerplate includes user authentication and OAuth2 provider capabilities out of the box.

🚀 Features

• User Authentication: Complete authentication system powered by Devise
• OAuth2 Provider: Full OAuth2 server implementation with Doorkeeper
• MCP Integration: Seamless Claude AI integration using fast-mcp
• Payment Processing: Integrated Stripe payments for tools with subscription options
• Modern Rails: Built on Rails 8.0.2 with the latest features
• Tailwind CSS: Beautiful, responsive UI with Tailwind
• Hotwire: Modern, fast frontend with Turbo and Stimulus

📋 Requirements

• Ruby 3.2+
• PostgreSQL
• Node.js & Yarn (for frontend assets)
• Stripe Account (for payment processing)

🔧 Setup

1. Clone the repository

git clone https://github.com/f/mcp-startup-boilerplate mcp-startup
cd mcp-startup

2. Install dependencies

bundle install
yarn install

3. Setup the database

rails db:create db:migrate db:seed

4. Configure Stripe (optional for payment features)

Set your Stripe API keys in your environment:

export STRIPE_PUBLISHABLE_KEY="pk_test_your_key"
export STRIPE_SECRET_KEY="sk_test_your_key"
export STRIPE_WEBHOOK_SECRET="whsec_your_webhook_key"

For development, you can also update these in config/initializers/stripe.rb

5. Start the server

rails server

Your application should now be running at http://localhost:3000

💳 Payment Integration

This application comes with built-in Stripe payment processing for MCP tools:

Subscription Plans

• Standard Plan: $0.03 per tool call with 40% savings compared to pay-as-you-go
• Enterprise Plan: $0.03 per tool call with additional benefits and unlimited usage

Pay-Per-Use Pricing

• Default pricing: $0.05 per tool call (can be customized per tool)

Payment Management

• User-friendly subscription management interface
• Detailed usage tracking dashboard
• Tool usage history and analytics

🧰 Paid Tool Framework

The application includes a PaidTool base class that allows you to easily create tools that require payment:

class YourPaidTool < PaidTool
  description "Your paid tool description"
  
  # Custom pricing (optional, defaults to $0.05)
  def price_cents
    8 # $0.08 per call
  end
  
  def call
    return { error: "User has no active subscription" } unless charge_user
  
    # Your implementation here after charge
  end
end

How PaidTool Works

1. When a tool is called, it first checks if the user has an active subscription
2. If subscribed, the tool executes and logs usage without additional charges
3. If not subscribed, the user is charged the tool's price via Stripe
4. All tool usage is tracked for analytics and billing purposes

Extending PaidTool

You can customize pricing and behavior by:

• Overriding price_cents to set custom pricing for specific tools
• Creating different tool categories with varying price points
• Adding tool-specific features for premium subscription tiers

🔒 OAuth2 Integration

This boilerplate comes with a complete OAuth2 server implementation powered by Doorkeeper. Key endpoints:

• OAuth Authorization: /oauth/authorize
• Token Endpoint: /oauth/token
• Application Registration: /oauth/applications
• Token Revocation: /oauth/revoke

The OAuth server supports:

• Authorization Code Flow
• Client Credentials Flow
• Refresh Token Flow
• PKCE Extension (S256 and plain)

🤖 MCP Integration

This boilerplate is pre-configured to work with Claude AI through the Model Context Protocol, enabling AI applications to securely access your application's data and functionality.

Available MCP Resources

• users/me - Access information about the authenticated user

Available MCP Tools

• MeTool - Get information about the currently authenticated user (do not delete it)
• FinancialCalculatorTool - Example paid calculator tool

🔌 Integrating with Claude

To connect your application with Claude:

1. Register your application in Claude Desktop or other Claude integrations
2. Configure your MCP server in Claude's configuration:

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://your-server-url/mcp/sse"
      ]
    }
  }
}

For Claude Desktop, this file is located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

🔧 Customization

Adding New MCP Tools

1. Create a new tool in app/tools/:

class YourTool < ApplicationTool
  description 'Your tool description'

  arguments do
    required(:param_name).filled(:string).description('Parameter description')
  end

  def call(param_name:)
    # Your implementation
    
    # Access the current authenticated user
    user = current_user
    # Do something with the user data
    { user_id: user.id, result: "Processed data for #{user.email}" }
  end
end

2. Register the tool in your MCP configuration

Adding New MCP Resources

1. Create a new resource in app/resources/:

class YourResource < ApplicationResource
  uri 'your/resource/path'
  resource_name 'Your Resource'
  description 'Your resource description'
  mime_type 'application/json'

  def content
    # Access the current authenticated user
    user = current_user
    
    JSON.generate({
      user_id: user.id,
      email: user.email,
      # Additional user-specific data
      custom_data: user.custom_data
    })
  end
end

2. Register the resource in your MCP configuration

Working with Current User

Both MCP Tools and Resources have access to the current_user method, which returns the authenticated user from the OAuth token. This allows you to:

• Retrieve user-specific data
• Perform user-authorized operations
• Maintain security by scoping operations to the authenticated user
• Build personalized AI experiences based on user context

For security reasons, always verify user permissions before exposing sensitive data or performing critical operations.

🛡️ Security Considerations

• All MCP endpoints require proper OAuth authentication
• User data is only accessible to authorized applications
• OAuth tokens can be revoked by users at any time
• PKCE extension is supported for public clients
• Stripe payments are securely processed with modern best practices

📚 Further Reading

• Doorkeeper Documentation
• fast-mcp Documentation
• Model Context Protocol Specification
• Devise Documentation
• Stripe Documentation

📝 License

This project is available under the MIT License.

👥 Contributing

Contributions, issues, and feature requests are welcome!