Which integrations are available for this server?

Provides ChatGPT app integration using the OpenAI Apps SDK (MCP), enabling tools, resources, and interactive widgets to be used within ChatGPT conversations through OAuth2 authentication.

How do I use ChatGPT App with OAuth2 + MCP + Privy?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ChatGPT App with OAuth2 + MCP + Privy show me my recent items" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

ChatGPT App with OAuth2 + MCP + Privy

A complete ChatGPT App implementation using the OpenAI Apps SDK (MCP), with OAuth2 authentication via Privy.io.

🏗️ Architecture

Backend: Express + MCP Server (TypeScript/Bun)
OAuth UI: React + Privy + React Router
Widgets: React components (rendered in ChatGPT)
Auth: OAuth2 with PKCE + Privy.io
Package Manager: Bun

📁 Project Structure

mcp2/
├── src/
│   ├── server/          # Express + MCP server
│   │   ├── oauth/       # OAuth2 endpoints
│   │   ├── mcp/         # MCP tools & resources
│   │   ├── api/         # Backend API integration
│   │   └── middleware/  # Auth middleware
│   ├── client/          # OAuth authorization UI
│   └── widgets/         # ChatGPT widget components
├── dist/
│   ├── client/          # Built OAuth UI
│   ├── widgets/         # Built widget bundles
│   └── server/          # Compiled server
└── package.json

🚀 Quick Start

Prerequisites

Bun installed
Privy.io account and app created
OpenSSL (for generating JWT keys)

1. Install Bun

curl -fsSL https://bun.sh/install | bash

2. Install Dependencies

bun install

3. Generate JWT Keys

# Generate RSA key pair for JWT signing
openssl genrsa -out private-key.pem 2048
openssl rsa -in private-key.pem -pubout -out public-key.pem

# Base64 encode for .env
echo "JWT_PRIVATE_KEY=$(cat private-key.pem | base64)"
echo "JWT_PUBLIC_KEY=$(cat public-key.pem | base64)"

# Clean up PEM files
rm private-key.pem public-key.pem

4. Configure Environment

cp .env.example .env
# Edit .env with your values:
# - PRIVY_APP_ID (from Privy dashboard)
# - PRIVY_APP_SECRET (from Privy dashboard)
# - JWT_PRIVATE_KEY (from step 3)
# - JWT_PUBLIC_KEY (from step 3)
# - BACKEND_API_URL (your existing backend)

5. Build & Run

IMPORTANT: Widgets must be built before starting the server!

# First time: Build widgets (required!)
bun run build:widgets

# Then start development server
bun run dev

The server will start at http://localhost:3002

🔧 Development

⚠️ Key Point: bun run dev does NOT automatically build widgets. You must build them separately!

There are three development workflows:

Option 1: Manual Build (Recommended for first-time setup)

# 1. Build widgets once
bun run build:widgets

# 2. Start server with auto-reload
bun run dev

# 3. Rebuild widgets manually when you change widget code
bun run build:widgets

# Terminal 1: Build widgets in watch mode (auto-rebuilds on changes)
bun run dev:widgets

# Terminal 2: Run server with auto-reload
bun run dev

Option 3: Run Everything (Most convenient)

# Runs both server AND widget watch mode simultaneously
bun run dev:all

Other Development Commands

# Type check
bun run type-check

# Run tests
bun run test

# Build everything for production
bun run build

Project Configuration

Server: src/server/index.ts

OAuth endpoints: /authorize, /token, /.well-known/*
MCP endpoint: /mcp
Health check: /health

OAuth UI: src/client/src/App.tsx

Authorization page with Privy login
Consent screen
Built with Vite + React + React Router

Widgets: src/widgets/src/

ListView: Interactive list with actions
Built as standalone bundles
Communicate via window.openai API

🧪 Testing

Test with MCP Inspector

# Terminal 1: Run server
bun run dev

# Terminal 2: Run MCP Inspector
bunx @modelcontextprotocol/inspector http://localhost:3002/mcp

Test with ngrok

# Expose local server
ngrok http 3002

# Copy the HTTPS URL (e.g., https://abc123.ngrok.app)
# Use this URL in ChatGPT Settings → Connectors

Connect to ChatGPT

Enable Developer Mode:
- ChatGPT Settings → Apps & Connectors → Advanced settings
- Enable "Developer mode"
Create Connector:
- Settings → Connectors → Create
- Name: "Your App Name"
- Description: "What your app does"
- Connector URL: https://your-server.com/mcp (or ngrok URL)
Test OAuth Flow:
- Start a new ChatGPT conversation
- Click + → More → Select your connector
- You'll be redirected to /authorize
- Log in with Privy
- Grant consent
- ChatGPT receives OAuth token
Test Tools:
- Ask ChatGPT: "Show me my items"
- The get-items tool will be called
- Widget will render in ChatGPT

📦 Production Build

# Build everything
bun run build

# Run production server
bun run start

# Or preview locally
bun run preview

Docker Deployment

# Build image
docker build -t chatgpt-app .

# Run container
docker run -p 3000:3000 --env-file .env chatgpt-app

Deploy to Fly.io

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Create app
fly launch

# Set secrets
fly secrets set PRIVY_APP_ID=xxx
fly secrets set PRIVY_APP_SECRET=xxx
fly secrets set JWT_PRIVATE_KEY=xxx
fly secrets set JWT_PUBLIC_KEY=xxx
fly secrets set BACKEND_API_URL=xxx

# Deploy
fly deploy

🔐 OAuth2 Flow

ChatGPT redirects user to /authorize?client_id=...&code_challenge=...
Server serves React UI (Privy login)
User authenticates with Privy
Frontend shows consent screen
User approves, server generates authorization code
Frontend redirects back to ChatGPT with code
ChatGPT exchanges code for access token at /token
Server validates PKCE, issues JWT
ChatGPT uses JWT for /mcp requests

🎨 Adding New Tools

1. Define Tool in src/server/mcp/tools.ts

{
  name: 'my-new-tool',
  description: 'What the tool does',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string' }
    },
    required: ['param']
  }
}

2. Implement Handler

async function handleMyNewTool(args: any, auth: any) {
  // Validate auth
  // Call backend API
  // Return structured response
}

_meta: {
  'openai/outputTemplate': 'ui://widget/my-widget.html',
}

🎨 Adding New Widgets

mkdir -p src/widgets/src/MyWidget

// src/widgets/src/MyWidget/index.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { MyWidget } from './MyWidget';

const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(<MyWidget />);

3. Configure Vite

// Update src/widgets/vite.config.ts
build: {
  lib: {
    entry: {
      'my-widget': 'src/MyWidget/index.tsx'
    }
  }
}

4. Register Resource

// src/server/mcp/resources.ts
await registerMyWidget(server, widgetPath);

📚 Environment Variables

Variable	Description	Required
`PRIVY_APP_ID`	Your Privy app ID	✅
`PRIVY_APP_SECRET`	Your Privy app secret	✅
`VITE_PRIVY_APP_ID`	Privy app ID (for frontend)	✅
`JWT_PRIVATE_KEY`	Base64-encoded RSA private key	✅
`JWT_PUBLIC_KEY`	Base64-encoded RSA public key	✅
`SERVER_BASE_URL`	Your server URL	✅
`BACKEND_API_URL`	Your existing backend URL	✅
`PORT`	Server port (default: 3000)	❌
`NODE_ENV`	Environment (development/production)	❌

🐛 Troubleshooting

Widgets not loading

# Build widgets first
bun run build:widgets

# Restart server
bun run dev

OAuth flow fails

Check SERVER_BASE_URL matches your actual URL
Verify Privy app ID is correct
Check JWT keys are properly base64-encoded
Ensure redirect URI is registered in ChatGPT

Token validation fails

Verify JWT keys are correct (public/private pair)
Check token hasn't expired (1 hour default)
Ensure aud claim matches your server URL

MCP Inspector can't connect

# Ensure server is running
bun run dev

# Try:
bunx @modelcontextprotocol/inspector http://localhost:3002/mcp