MCP Server for ChatGPT Apps

A Model Context Protocol (MCP) server with interactive React components for ChatGPT Apps.

What is This?

This project implements an MCP server that works with ChatGPT Apps SDK, featuring:

• SSE-based MCP server - HTTP server using Server-Sent Events

• Interactive React widgets - Components that render inline in ChatGPT

• Calculator example - A fully functional calculator with history

• Modern build system - Vite + React + TypeScript + Tailwind CSS

Project Structure

mcp-server/
├── server/
│   └── src/
│       └── server.ts         # MCP server with SSE transport
├── web/
│   └── src/
│       ├── calculator/       # Calculator React component
│       ├── types.ts          # TypeScript definitions for window.openai
│       ├── use-openai-global.ts  # Hook for ChatGPT state
│       ├── use-widget-state.ts   # Hook for widget persistence
│       └── index.css         # Global styles
├── assets/                   # Built components (generated)
├── scripts/
│   └── post-build.js         # HTML generation script
├── vite.config.ts            # Vite build configuration
├── tailwind.config.ts        # Tailwind CSS config
└── package.json              # Root dependencies

Installation

1. Install Dependencies

# Install root dependencies (React, Vite, Tailwind)
npm install

# Install server dependencies (MCP SDK)
cd server && npm install && cd ..

2. Build Components

npm run build

This generates bundled React components in the assets/ directory.

Running the Server

Start the MCP Server

npm run server

The server will start on http://localhost:8000 with these endpoints:

• GET /mcp - SSE stream

• POST /mcp/messages?sessionId=... - Message handler

Testing with ChatGPT

Option 1: Local Testing with ngrok

1. Start the server:

   npm run server

2. Expose with ngrok:

   ngrok http 8000

3. Add to ChatGPT:

   • Go to ChatGPT Settings > Connectors

   • Add connector with URL: https://YOUR-ID.ngrok-free.app/mcp

4. Use in ChatGPT:

   • Add the connector to your conversation

   • Ask: "Show me a calculator" or "Open calculator"

   • The interactive calculator widget will appear!

Option 2: Production Deployment

1. Set base URL for assets:

   export BASE_URL=https://your-cdn.com
   npm run build

2. Deploy:

   • Upload assets/ to a CDN or static hosting (with CORS enabled)

   • Deploy the MCP server with HTTPS

   • Register in ChatGPT with your server URL

Available Tools

1. Calculator (with React UI)

• Tool: calculator

• Description: Interactive calculator widget with history

• Features:

  • Basic arithmetic operations

  • Calculation history (last 5 calculations)

  • Dark/light theme support

  • State persistence across turns

2. Get Current Time

• Tool: get_current_time

• Returns: Current time in ISO format

3. Echo

• Tool: echo

• Returns: Echoes back your message

Development

Run Dev Server (with hot reload)

npm run dev

Visit http://localhost:4444 to preview components.

Adding New Components

1. Create component in web/src/your-component/index.tsx:

import React from "react";
import { createRoot } from "react-dom/client";
import { useOpenAiGlobal } from "../use-openai-global";

function App() {
  const toolOutput = useOpenAiGlobal("toolOutput");
  const theme = useOpenAiGlobal("theme");
  
  return (
    <div className={theme === "dark" ? "dark" : ""}>
      <h1>Your Component</h1>
      {/* Your UI */}
    </div>
  );
}

createRoot(document.getElementById("your-component-root")!).render(<App />);

2. Update Vite config (vite.config.ts):

input: {
  calculator: path.resolve(__dirname, "web/src/calculator/index.tsx"),
  "your-component": path.resolve(__dirname, "web/src/your-component/index.tsx"),
},

3. Update post-build script (scripts/post-build.js):

const components = ["calculator", "your-component"];

4. Add widget to server (server/src/server.ts):

const widgets: Widget[] = [
  // ... existing widgets
  {
    id: "your-component",
    title: "Your Component",
    templateUri: "ui://widget/your-component.html",
    invoking: "Loading your component",
    invoked: "Component ready",
    html: readWidgetHtml("your-component"),
    responseText: "Component rendered!",
  },
];

5. Build and test:

npm run build
npm run server

Key Features

window.openai API

Components have access to:

window.openai.theme              // "light" | "dark"
window.openai.displayMode        // "inline" | "pip" | "fullscreen"
window.openai.toolOutput         // Data from tool call
window.openai.widgetState        // Persisted component state
window.openai.callTool(name, args)  // Call MCP tools
window.openai.sendFollowUpMessage({ prompt }) // Send to ChatGPT

Custom Hooks

// Subscribe to ChatGPT state
const theme = useOpenAiGlobal("theme");

// Persist component state
const [state, setState] = useWidgetState({ count: 0 });

Troubleshooting

"Widget assets not found"

Run npm run build to generate component bundles.

CORS errors

Ensure your server has CORS enabled (already configured in server.ts).

Components not rendering

1. Check browser console for errors

2. Verify assets are accessible at BASE_URL

3. Ensure HTML files reference correct JS/CSS paths

Resources

• OpenAI Apps SDK Documentation

• MCP Specification

• Example Apps Gallery

License

ISC