Football MCP Server

An example Rails 8 application that demonstrates how to build a Model Context Protocol server with interactive UI components using the official Ruby MCP SDK and the OpenAI Apps SDK.

✨ OpenAI Apps SDK Example - This application highlights how to use the OpenAI Apps SDK to build out UI components for your Rails MCP server, including React widgets that render inside ChatGPT using Streamable HTTP transport and Server-Sent Events (SSE).

Features

• Streamable HTTP transport - The recommended transport for ChatGPT integration
• Server-Sent Events (SSE) - Real-time streaming of tool responses
• Session management - Proper handling of multiple concurrent clients
• React 19 widgets - Interactive UIs that render inside ChatGPT
• Component registry pattern - Reusable widget architecture for rapid development
• Upcoming schedule widget - Interactive ticket-purchase CTA powered by the OpenAI Apps SDK
• In-widget follow-ups - Live scores widget can trigger follow-up prompts (via sendFollowUpMessage) to fetch deeper data without typing

⚠️ Production Warning

This application is NOT production-ready. It uses in-memory session storage which:

• Does not work with multiple servers or processes
• Loses all sessions on restart
• Is suitable only for development, demos, and single-server deployments

For production use, implement Redis-backed sessions or use stateless mode.

Screenshots

Live Scores Widget

The Live Scores Widget displays real-time football game scores in an interactive React component rendered inside ChatGPT.

Team Info Resource

The Team Info resource provides structured NFL team data including divisions, colors, and stadium information.

Setup

bundle install
npm install
cp .env.example .env
# Edit .env and set BASE_URL to your tunnel URL for ChatGPT testing

Start the server:

# Recommended: Start everything with one command (Rails + JS build + Cloudflare Tunnel)
# Note: Requires cloudflared to be installed and configured
bin/dev

# Alternative: For local testing only (no HTTPS tunnel, no auto-rebuild)
bin/rails server

Build React widgets manually:

# One-time build
npm run build

# Watch mode (rebuilds on changes) - not needed if using bin/dev
npm run watch

Run tests:

bin/rails test

Run linter:

rubocop

ChatGPT / OpenAI Apps SDK Integration

HTTPS Tunneling for Development

ChatGPT requires an HTTPS endpoint to connect to your local development server. You have several options:

Option 1: Cloudflare Tunnel (Recommended)

• No browser warnings or interstitials
• Works with your own domain
• Free tier available
• Install cloudflared and configure in Procfile.dev:

  tunnel: cloudflared tunnel run your-tunnel-name
  

• More stable for long development sessions

Option 2: ngrok (Paid Plan)

• Free tier shows browser warnings that break ChatGPT integration
• Paid plans ($8+/month) remove the browser warning
• Simple setup: ngrok http 3000
• Good for quick testing with paid account

Option 3: Other Tunneling Services

• localhost.run - SSH-based tunneling, no installation required
• Tailscale Funnel - If you use Tailscale for networking
• Bore - Rust-based open source alternative
• VS Code Port Forwarding - If using GitHub Codespaces or VS Code Remote

Important: Free ngrok accounts show an interstitial "Visit Site" warning page that prevents ChatGPT from loading your resources. You'll need either a paid ngrok account or an alternative tunneling solution.

Setting up for ChatGPT

1. Configure your Cloudflare Tunnel in Procfile.dev:

   tunnel: cloudflared tunne
   

... View full README on GitHub