home / mcp / chatgpt apps sdk next.js starter mcp server

ChatGPT Apps SDK Next.js Starter MCP Server

Provides an OpenAI Apps SDK compatible MCP server with tools and resources for widget rendering in ChatGPT.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "devsung94-next-mcp-test": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

You set up an OpenAI Apps SDK compatible MCP server inside a Next.js app to expose tools and resources that render as widgets in ChatGPT. This starter shows how to register tools and resources, serve iframe content, and patch browser APIs so your app works smoothly inside the ChatGPT environment.

How to use

You connect a client to an MCP server that is exposed under the /mcp route. The server provides tools and resources that ChatGPT can call, and the responses render within ChatGPT as widgets in an iframe.

How to install

Prerequisites: you need Node.js and npm (or pnpm) installed on your machine.

npm install
# or
pnpm install

Configuration and core files

You will configure the MCP server route, asset loading, CORS handling, and the SDK bootstrap so the app runs correctly inside ChatGPT. The core files include an MCP route, a Next.js layout with the SDK bootstrap, a CORS middleware, and an asset prefix setup.

// app/mcp/route.ts
// Core MCP server for tool and resource registration
// ... Tool registration with OpenAI metadata and Resource registration ...
```

```ts
// next.config.ts
const nextConfig: NextConfig = {
  assetPrefix: baseURL,  // Prevents 404s on /_next/ files in iframe
};
export default nextConfig;
```

```ts
// middleware.ts
import { NextRequest } from 'next/server'
export function middleware(request: NextRequest) {
  if (request.method === 'OPTIONS') {
    // Return 204 with CORS headers
  }
  // Add CORS headers to all responses
}
```

```tsx
// app/layout.tsx
'import { NextChatSDKBootstrap } from "@chatgpt/apps-sdk";

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <NextChatSDKBootstrap baseUrl={baseURL} />
      </head>
      <body>{children}</body>
    </html>
  );
}

How the MCP server works

The server exposes tools and resources; a tool invocation returns a resource reference via templateUri. ChatGPT fetches the HTML content of the resource to render a widget, and the client hydrates inside the iframe using patched browser APIs.

Key patches in the bootstrap ensure smooth operation inside the ChatGPT iframe, including history management, fetch rewrites for same-origin requests, and preventing the host from altering the root HTML.

Deployment and testing

You can test locally at the following MCP server URL.

http://localhost:3000/mcp
```

You can deploy to a hosting platform and use the standard MCP URL format with the /mcp path, such as https://your-app.vercel.app/mcp.