Build a ChatGPT MCP App in Next.js: Tool & UI
Learn how to build a ChatGPT MCP App using Next.js by separating tools, widgets, and sidebars into a clean, open-source architecture.
Stock photo for illustration only, not from the actual event
- Build a ChatGPT MCP App in Next.js using mcp-handler
- Decouple tools, widgets, and sidebars into distinct components
- Serve static HTML UI via resource URIs and custom MIME types
- Test locally with MCP Inspector before connecting to ChatGPT
Getting a Model Context Protocol tool to respond is one hurdle, but rendering its user interface inside ChatGPT is an entirely different challenge. When developing a ChatGPT MCP App with Next.js, organizing the moving parts by separating the tool, widget, and sidebar rather than treating them as a monolithic feature proves highly beneficial for developers.
A lightweight, open-source starter project demonstrates this exact architecture without overwhelming boilerplate code, dividing the application into three essential pillars:
- The Tool: Operates independently of its user interface, making no external API calls and returning structured text responses even if the client cannot render widgets.
- The UI Resource: Serves static HTML utilizing the specialized MIME type
text/html;profile=mcp-app, linked via resource identifiers rather than public website URLs. - The Endpoint: Handled entirely within a Next.js App Router route, exporting request handlers for both GET and POST operations via
mcp-handler.
To register app tools, developers utilize registerAppTool from @modelcontextprotocol/ext-apps/server, complete with a Zod input schema and an explicit readOnlyHint. The tool metadata leverages the ui.resourceUri field to bind the tool to its inline UI, alongside optional entrypoints for conversation panels and sidebars in compatible client environments.
Decoupling backend logic from frontend presentation in AI agent applications is a robust architectural pattern. It ensures that core data models and tool executions remain functional and testable even when client-side rendering capabilities vary or encounter compatibility issues across different ChatGPT interfaces.
Stock photo for illustration only, not from the actual event
Because this Hello World example contains no databases, paid API keys, or user authentication systems, getting started is straightforward. Developers can clone the starter repository, install dependencies, and execute local testing workflows:
- Clone the ChatGPT MCP App Starter and install dependencies
- Run the development server using
npm run dev - Inspect tool execution via
npx @modelcontextprotocol/inspector@latest - Connect securely using the local
/api/mcpendpoint URL
When troubleshooting deployment issues, developers should verify resource URIs, MIME types, and client support before attempting server rewrites if the tool executes successfully but the UI fails to render. Similarly, 401 or 403 HTTP status errors should prompt a review of deployment protection and authentication rules rather than blindly disabling core security measures.
Source: Dev.to
Found something wrong in this article? Report an issue with this article
Comments
Leave a Comment