A new type of app is emerging with the development of LLMs and AI-native apps. It lives inside an AI chat (like ChatGPT) rather than being a fully native web or mobile app.
In this tutorial, you’ll learn how to build an MCP (Model Context Protocol) server from scratch, including a UI you can use as a ChatGPT app with authentication and a database.
You’ll go through the process of building, testing, adding the ChatGPT app as a connector, and submitting it to publish to the app directory. This will let you build the app on three levels:
-
Level one: you will build your basic MCP Server that returns textual data.
-
Level two: you will build a UI for your MCP Server to be used within an LLM UI.
-
Level three: you will add authentication and a database to your MCP Server.
To fully understand this article, you’ll need to have basic knowledge of:
-
Web development
-
JavaScript
-
React and React Native
-
SQL and databases
What We’ll Cover:
What is an MCP Server?
A Model Context Protocol (MCP) server is a program that exposes tools, resources, and prompts to an AI application through a standard protocol. An MCP server can provide read-only context, callable tools, or reusable prompt templates that help extend what an AI application can do.
A developer builds or configures the MCP server, and an MCP client inside a host application connects to it. The application can then allow the model to discover available capabilities and, when appropriate, invoke tools or fetch resources via the MCP protocol to help complete a task.
What Can You Do with an MCP Server?
An MCP server lets an AI application work with information and systems outside the model itself. For example, it can help the model look up current information, save and retrieve user data, search documents, or trigger actions in another application.
In practice, one MCP server might connect to an online database, while another might work with files on your local machine. This makes it possible to build AI workflows that are more useful, practical, and connected to real tools.
Level 1: How to Build Your Own MCP Server
In this tutorial, you’ll learn how to build an MCP server using the default HTTP server from Node.js, Supabase for the database and authentication, and the official MCP server SDK. Then you’ll deploy it to DigitalOcean and publish your app on ChatGPT.
That means you’ll do two steps here:
-
First step: connect your deployed MCP server to ChatGPT as an app/connector so it can be used within ChatGPT.
-
Second step: submit the app for review and, if approved, publish it to the ChatGPT app directory.
The MCP server SDK isn’t the only tool or framework for building your own MCP server. You can use other SDKs and tools for that if you prefer. But to simplify the first steps, here I’ve decided to use the more straightforward tools.
Step 0: Prepare your project
You’re going to write a full project here, so you should start by creating packages and initializing the project. To do this, follow these steps:
-
Create a new folder with the project name. For this example, you can use
mcp_todo. -
Navigate to this new folder.
-
Open the terminal in this folder.
-
Initialize the npm project with
npm init --init-type=module -yto create a JavaScript package file and add the packages to the project with ES6 support. -
Initialize Git with
git initin the project to enable version control and track changes. -
Install related packages that you’re going to use in your project:
-
The packages are Supabase, the MCP SDK (which we’ll cover in step 2), and the zod validation package for validating LLM inputs and data.
npm install @modelcontextprotocol/sdk zod @supabase/supabase-js
-
-
Create a
.gitignorefile and add thenode_modulesto it so that it won’t be tracked by Git. -
Add the current state of the project to your Git tracker by writing the following:
With this, you’ve created a new project for yourself that you can use as a starting point for managing and following the project.
Step 1: Create a Node.js Server
To start the project, you’ll need to create a simple Node.js server, which you can do by creating a new file named server.js and writing the following code:
import { createServer } from "node:http";
const port = Number(process.env.PORT ?? 8787);
const httpServer = createServer(async (req, res) => {
console.log(`${req.method} ${req.url}`);
if (!req.url) {
res.writeHead(400).end("Missing URL");
return;
}
const url = new URL(req.url, ` ?? "localhost"}`);
res.writeHead(404).end("Not Found");
});
httpServer.listen(port, () => {
console.log(`Todo MCP server listening on press Ctrl+C to stop`);
});
This is a simple Node server that you’ll use as the base for building your MCP Server.
To build your MCP server, you’ll need to set it up using the MCP Server SDK. After that, you’ll need to define two things: the tools you’ll show the LLM and the UI and resources the LLM will use to render.
To define the tools and UI concepts, you’ll use the MCP Server SDK.
Step 2: Setting Up MCP Server SDK
To set up and start the MCP server, you need to have the following:
-
Tools: The functions exposed by MCP Server to an LLM, enabling the LLM to interact with the server and external systems. Like calling an API, performing a computation, or querying a database.
-
Resources (optional): Data the MCP Server shares with an LLM. For example, a file, database schema, or an HTML UI to use inside the LLM Chat UI as an embedded frame.
You can start the server by adding this line of code at the top of the server.js file:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
function createTodoServer() {
const server = new McpServer({ name: "todo-app", version: "0.1.0" });
return server;
}
Then add a tool and resources using the following function signature:
server.registerTool(
"NAME",
{},
async (args, meta) => { }
);
You can think about the tool registrar as your endpoint to the MCP Server. The LLM will check it and, based on the name and metadata, start processing the data using the arguments and results you have in this tool.
Today, you’re going to build three simple tools:
-
Add todo
-
Update todo
-
List todos
They all look a bit similar, but you’ll see how to write them all to understand the concepts in the next sections.
Step 3: Add MCP Server Tools – Create and Add a Todo
To start with, when adding todos, you’ll need a simple in-memory array to manipulate. You can create the array outside the create server function to access it throughout the server.
let todos = [];// outside the createTodoServer function block
let nextId = 1; // outside the createTodoServer function block (this is a mock id for your todos)
After the array, you’ll need to have two more supporting functions: first, the validator for the tools, which specifies the expected input types from the LLM.
At the top of the file, you should import the zod library:
import { z } from "zod";
Then you can write the helper function to validate it and tell the LLM what to expect from them:
const addTodoInputSchema = {
title: z.string().min(1),
}; // outside the createTodoServer function block
Next, you’ll need the return function, which you can use with other functions to have a unified return function for the tools
const replyWithTodos = (message) => ({
content: message ? [{ type: 'text', text: message }] : [],
structuredContent: { tasks: todos },
}); //outside the createTodoServer function block
Then you can register the add todo function in the server, inside the createTodoServer function block, before return server:
server.registerTool(
'add_todo',
{
title: 'Add todo',
description: 'Creates a todo item with the given title.',
inputSchema: addTodoInputSchema,
_meta: {
'openai/toolInvocation/invoking': 'Adding todo',
'openai/toolInvocation/invoked': 'Added todo',
},
},
async (args) => {
const title = args?.title?.trim?.() ?? '';
if (!title) return replyWithTodos('Missing title.');
const todo = { id: `todo-${nextId++}`, title, completed: false };
todos = [...todos, todo];
return replyWithTodos(`${todo.title}`);
},
); // inside the createTodoServer function block
In the above code, you’ve added the tool name and used a simple approach to add the todos to the in-memory array you already identified. The trick here is to validate the data before adding it and create the related object for it.
In the metadata, you’ve added the title, description, inputSchema, and _meta for OpenAI to use while rendering this. You’ll get a rendering, add a todo when the AI adds it, and have the latest version of the added todo when it’s finished.
At the same time, you’ve added the input schema so the LLM knows what to provide when invoking your server, and you’ve added a reply helper function to handle your todos. It’s a simple function that shows the todos in a structured way for LLMs to understand.
Step 4: List Todos from MCP Server
To list the todos, you can use a simple list function to show the todos without any changes. In the code below, you use the same concept for naming, metadata, and description context as you provided before. You’re also using the previous helper function to return the todos that you have in memory. You should write this code inside the createTodoServer function block.
server.registerTool(
'list_todos',
{
title: 'List todos',
description: 'Lists all todo items.',
_meta: {
'openai/toolInvocation/invoking': 'Listing todos',
'openai/toolInvocation/invoked': 'Listed todos',
},
},
async () => {
return replyWithTodos();
},
);
Step 5: Add Todo Complete Functions
To complete and edit todos, you can create a new tool with that name that takes the todo ID and returns the updated todos. To do this, you need to add the helper function for validating the request outside the createTodoServer:
const completeTodoInputSchema = {
id: z.string().min(1),
};
Then inside the createTodoServer function, you can add the following:
server.registerTool(
'complete_todo',
{
title: 'Complete todo',
description: 'Marks a todo as done by id.',
inputSchema: completeTodoInputSchema,
_meta: {
'openai/toolInvocation/invoking': 'Completing todo',
'openai/toolInvocation/invoked': 'Completed todo',
},
},
async (args) => {
const id = args?.id;
if (!id) return replyWithTodos('Missing todo id.');
const todo = todos.find((task) => task.id === id);
if (!todo) {
return replyWithTodos(`Todo ${id} was not found.`);
}
todos = todos.map((task) =>
task.id === id ? { ...task, completed: true } : task,
);
return replyWithTodos(`Completed "${todo.title}".`);
},
);
In this tool, you used the same function definition as for list todos, while adding extra guards to check whether the LLM has returned the ID and whether that ID is correct. You should always manually check the data you have before processing it, since LLMs can hallucinate and aren’t required to validate their inputs.
Now you can commit your code to Git and track it in the tree:
Step 6: Connect Your MCP Server with the Node.js Server
Since you have written the main functions for the MCP server, you need to connect your MCP server to the Node.js HTTP server.
To do that, you need to write the streamable function and the related code. You will use this code on top of the server code from step 1 as a replacement, since it includes more functions to handle the MCP server.
First, import the StreamableHTTPServerTransport function:
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
Then you can copy the next code and replace it with the server code, which has the server’s structure, to use in your project.
const port = Number(process.env.PORT ?? 8787);
const MCP_PATH = '/mcp';
const httpServer = createServer(async (req, res) => {
if (!req.url) {
res.writeHead(400).end('Missing URL');
return;
}
const url = new URL(req.url, ` ?? 'localhost'}`);
// handle the options call for the endpoint
if (req.method === 'OPTIONS' && url.pathname === MCP_PATH) {
res.writeHead(204, {
'Access-Control-Allow-Origin': '*',
'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
'Access-Control-Allow-Headers': 'content-type, mcp-session-id',
'Access-Control-Expose-Headers': 'Mcp-Session-Id',
});
res.end();
return;
}
// handles normal get method for the main link
if (req.method === 'GET' && url.pathname === '/') {
res.writeHead(200, { 'content-type': 'text/plain' }).end('Todo MCP server');
return;
}
// here you are handling your MCP calls with streamable HTTP
const MCP_METHODS = new Set(['POST', 'GET', 'DELETE']);
if (url.pathname === MCP_PATH && req.method && MCP_METHODS.has(req.method)) {
res.setHeader('Access-Control-Allow-Origin', '*');
res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
const server = createTodoServer();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined, // stateless mode
enableJsonResponse: true,
});
res.on('close', () => {
transport.close();
server.close();
});
try {
await server.connect(transport);
await transport.handleRequest(req, res);
} catch (error) {
console.error('Error handling MCP request:', error);
if (!res.headersSent) {
res.writeHead(500).end('Internal server error');
}
}
return;
}
res.writeHead(404).end('Not Found');
});
httpServer.listen(port, () => {
console.log(
`Todo MCP server listening on
);
});
In this code, you’re running the main HTTP server to handle the requests. The server exposes a /mcp endpoint for MCP clients and connects each request to a stateless MCP server using Streamable HTTP.
Now you can commit your code to Git and track it in the tree:
How to Test Your MCP Server
Now you can test the basic structure of your MCP server by running the following code:
node server.js
By using this command, you’ll run the server you created in the previous steps. It will make it active and listen to changes at . After running server.js, you need to open the inspector, a tool that helps you see the MCP server registration and the endpoints and tools you need to use and run in a secure environment.
npx @modelcontextprotocol/inspector@latest --server-url --transport http
When you run the previous command, you can see that you have a connection to your MCP, and you need to run it and use it through the inspector UI. Using the inspector UI will help you test your MCP server without connecting it to any external services and test the inputs and outputs locally.
To test your tools, connect to the server first, and then you can see and explore them.
After writing this code, you may wonder: what UI could I show the user through an LLM? If you run your project right now, you’ll only get text results as LLM chat answers. But if you build a UI, you can improve your LLM’s experience. In the next section, that’s what we’ll tackle.
Level 2: How to Build the UI
With the previous code, you built a simple MCP server that adds todos to a todo list and marks them as complete from the app. Now you’re going to explore the registerResource tool, which registers a UI resource of your design so ChatGPT can use it.
Resources are the LLM-specific data provided by your MCP Server. You can share your UI with the LLM so it can use it to display additional data and widgets in the chat.
To share the UI, you need to have an HTML file that relies on your MCP server data and uses the MCP server. So for that, you’ll create a new HTML file.
Step 1: Create the HTML File to Show the UI
The TodoHTML you provided earlier should be an HTML file that can communicate with the Server and the ChatGPT UI. The UI will look like the following image:
To build such a UI you saw previously, you need to create a public/todo-widget.html file and write the following structured code:
Todo list
Todo list
id = todo-list. But the tricky part is the JavaScript module you're going to add to it.
Step 2: Add a JavaScript Module to Handle MCP Server Data.
To add the JavaScript module and code, you'll write all the code below inside theconst listEl = document.querySelector("#todo-list");
const formEl = document.querySelector("#add-form");
const inputEl = document.querySelector("#todo-input");
windows.openai code. This will allow you to receive results and responses from ChatGPT while using your MCP server.
For this case, you'll use the following:
callTool calls the tools from your MCP server by name, and toolOutput is the result of the tools you get from your MCP.
To create the first todos and show them, you can use the toolOutput and get the output from there to use in your UI. Here's a code example:
let tasks = [...(window.openai?.toolOutput?.tasks ?? [])];
const render = () => {
listEl.innerHTML = '';
tasks.forEach((task) => {
const li = document.createElement('li');
li.dataset.id = task.id;
li.dataset.completed = String(Boolean(task.completed));
const label = document.createElement('label');
label.style.display = 'flex';
label.style.alignItems="center";
label.style.gap = '10px';
const checkbox = document.createElement('input');
checkbox.type="checkbox";
checkbox.checked = Boolean(task.completed);
const span = document.createElement('span');
span.textContent = task.title;
label.appendChild(checkbox);
label.appendChild(span);
li.appendChild(label);
listEl.appendChild(li);
});
};
const updateFromResponse = (response) => {
if (response?.structuredContent?.tasks) {
tasks = response.structuredContent.tasks;
render();
}
};
const handleSetGlobals = (event) => {
const globals = event.detail?.globals;
if (!globals?.toolOutput?.tasks) return;
tasks = globals.toolOutput.tasks;
render();
};
window.addEventListener("openai:set_globals", handleSetGlobals, {
passive: true,
});
const mutateTasksLocally = (name, payload) => {
if (name === "add_todo") {
tasks = [
...tasks,
{ id: crypto.randomUUID(), title: payload.title, completed: false },
];
}
if (name === "complete_todo") {
tasks = tasks.map((task) =>
task.id === payload.id ? { ...task, completed: true } : task
);
}
if (name === "set_completed") {
tasks = tasks.map((task) =>
task.id === payload.id
? { ...task, completed: payload.completed }
: task
);
}
render();
};
const callTodoTool = async (name, payload) => {
if (window.openai?.callTool) {
const response = await window.openai.callTool(name, payload);
updateFromResponse(response);
return;
}
mutateTasksLocally(name, payload);
};
formEl.addEventListener("submit", async (event) => {
event.preventDefault();
const title = inputEl.value.trim();
if (!title) return;
await callTodoTool("add_todo", { title });
inputEl.value = "";
});
listEl.addEventListener("change", async (event) => {
const checkbox = event.target;
if (!checkbox.matches('input[type="checkbox"]')) return;
const id = checkbox.closest("li")?.dataset.id;
if (!id) return;
if (!checkbox.checked) {
if (window.openai?.callTool) {
checkbox.checked = true;
return;
}
mutateTasksLocally("set_completed", { id, completed: false });
return;
}
await callTodoTool("complete_todo", { id });
});
render();
Step 3: Styling your UI
Since you've created the HTML tags and JavaScript code for your UI, you can improve the look of it by styling it the way you like with CSS. For that, you can use the following code and add it inside thestyle tag in the HTML file.
:root {
color: #0b0b0f;
font-family:
"Inter",
system-ui,
-apple-system,
sans-serif;
}
html,
body {
width: 100%;
min-height: 100%;
box-sizing: border-box;
}
body {
margin: 0;
padding: 16px;
background: #f6f8fb;
}
main {
width: 100%;
max-width: 360px;
min-height: 260px;
margin: 0 auto;
background: #fff;
border-radius: 16px;
padding: 20px;
box-shadow: 0 12px 24px rgba(15, 23, 42, 0.08);
}
h2 {
margin: 0 0 16px;
font-size: 1.25rem;
}
form {
display: flex;
gap: 8px;
margin-bottom: 16px;
}
form input {
flex: 1;
padding: 10px 12px;
border-radius: 10px;
border: 1px solid #cad3e0;
font-size: 0.95rem;
}
form button {
border: none;
border-radius: 10px;
background: #111bf5;
color: white;
font-weight: 600;
padding: 0 16px;
cursor: pointer;
}
input[type="checkbox"] {
accent-color: #111bf5;
}
ul {
list-style: none;
padding: 0;
margin: 0;
display: flex;
flex-direction: column;
gap: 8px;
}
li {
background: #f2f4fb;
border-radius: 12px;
padding: 10px 14px;
display: flex;
align-items: center;
gap: 10px;
}
li span {
flex: 1;
}
li[data-completed="true"] span {
text-decoration: line-through;
color: #6c768a;
}
Step 4: Add the UI to your MCP Server:
Writing the HTML file isn't enough to add resources to your project. You also need to upload the HTML and resources to the MCP server and configure the server to use them using the tools you provided. To make your MCP server aware of the UI and HTML, you need to add extra functions to the MCP server and some _meta keys to the server tools. Here's the signature of the resources function that the MCP server will use. This signature tells the LLM what type of file to read and which resources to use when it returns the output template. You'll add this code to your server.js and your MCP server, then create your own HTML file that includes the design and UI.registerResource(name: string, uriOrTemplate: string, config: ResourceMetadata, readCallback: ReadResourceCallback): RegisteredResource;
import { readFileSync } from "node:fs";
const todoHtml = readFileSync("public/todo-widget.html", "utf8");
createTodoServer function, which will tell the LLM the type of HTML to use and where to find it.
server.registerResource(
"todo-widget",
"ui://widget/todo.html",
{},
async () => ({
contents: [
{
uri: "ui://widget/todo.html",
mimeType: "text/html+skybridge",
text: todoHtml,
_meta: { "openai/widgetPrefersBorder": true },
},
],
})
);
- mimeType: the type of the file you provided. You added Skybridge, which is the OpenAI protocol that renders the HTML inside an iframe in the ChatGPT UI.
- URI: a specific name of your widget
- Text: Which is your HTML file
- _meta: specific details for ChatGPT
Step 5: Update Your MCP Server to Handle the UI
Now that you've written the HTML pages to show a simple UI for your data and added the HTML as a resource to your MCP server, you'll add the following code to the _meta section in the MCP server tools so it can handle and render the HTML output when needed. Without this, the LLM will only return the output without returning the UI:_meta: {
"openai/outputTemplate": "ui://widget/todo.html",
"openai/toolInvocation/invoking": "Listing todos",
"openai/toolInvocation/invoked": "Listed todos",
},
server.registerTool(
'list_todos',
{
title: 'List todos',
description: 'Lists all todo items.',
_meta: {
"openai/outputTemplate": "ui://widget/todo.html",
'openai/toolInvocation/invoking': 'Listing todos',
'openai/toolInvocation/invoked': 'Listed todos',
},
},
async () => {
return replyWithTodos();
},
);
How to Test Your ChatGPT App
After adding the UI to your MCP server, you can run and test the project on ChatGPT by doing the following: First, run your server normally with:node server.js
ngrok http 8787
Then you can add your server to ChatGPT and test it thoroughly.
You'll need to write the following data in this input:
- App name
- Descripiton
-
Connection: as a server URL with your ngrok link from the terminal, with the
mcpslash - No authentication, since we haven't implemented it yet
After adding the app, you can use it in the conversation by calling it with the app name by writing @app_name
Here are the examples from ChatGPT:
Here is the example of completing a step:
In the next section, you'll add authentication and a database to your project to move it to the next level.
Level 3: How to Add Supabase (Auth and Database) to the MCP Server
To add authentication and a backend, you'll need a backend/SQL server and an authentication server. The easiest current way is to use a service that can provide that. For this, you'll use Supabase. To start, you'll create a new Supabase project for your backend. The project will include a simple table for the todos you have created in your MCP server and use it as the backend. Then you'll implement authentication.Step 1: Create the Todos Table
To create the table, navigate through your project on Supabase and use the SQL editor to write the following code to add the todos:-- Enable pgcrypto for gen_random_uuid
CREATE EXTENSION IF NOT EXISTS pgcrypto;
-- Create todos table
CREATE TABLE IF NOT EXISTS public.todos (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
user_id uuid REFERENCES auth.users(id) ON DELETE CASCADE,
title text NOT NULL,
completed boolean NOT NULL DEFAULT false,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now()
);
-- Function to keep updated_at current
CREATE OR REPLACE FUNCTION public.set_updated_at()
RETURNS trigger
LANGUAGE plpgsql
AS $$
BEGIN
NEW.updated_at = now();
RETURN NEW;
END;
$$;
-- Attach trigger
DROP TRIGGER IF EXISTS set_updated_at_trigger ON public.todos;
CREATE TRIGGER set_updated_at_trigger
BEFORE UPDATE ON public.todos
FOR EACH ROW
EXECUTE FUNCTION public.set_updated_at();
-- Enable Row Level Security
ALTER TABLE public.todos ENABLE ROW LEVEL SECURITY;
-- Users can read only their own todos
CREATE POLICY "Users can view their own todos"
ON public.todos
FOR SELECT
TO authenticated
USING (user_id = (SELECT auth.uid()));
-- Users can insert only their own todos
CREATE POLICY "Users can insert their own todos"
ON public.todos
FOR INSERT
TO authenticated
WITH CHECK ((user_id IS NOT NULL)
AND (user_id = (SELECT auth.uid())));
-- Users can update only their own todos
CREATE POLICY "Users can update their own todos"
ON public.todos
FOR UPDATE
TO authenticated
USING (user_id = (SELECT auth.uid()))
WITH CHECK (user_id = (SELECT auth.uid()));
-- Users can delete only their own todos
CREATE POLICY "Users can delete their own todos"
ON public.todos
FOR DELETE
USING (auth.uid() = user_id);
-- Index for faster user-specific queries
CREATE INDEX IF NOT EXISTS idx_todos_user_id
ON public.todos(user_id);
Step 2: Enabling the MCP Server to Connect with Supabase Auth
For this, you need to do the following: To enable the OAuth server on your Supabase, you need to go to https://supabase.com/dashboard/project/_/auth/oauth-server, then follow the next steps:- Toggle Enable OAuth server
- Allow dynamic apps
- Create your consent page: the page that LLM tools will show users when they need to grant access to the data.
To use the consent page and see it in action, you'll need to implement the OAuth server in your MCP server first. This is what you'll do in the next section.
Step 3: Create a Proxy Server for the MCP Server to Handle the Auth.
After enabling the OAuth server in Supabase, you can start implementing the OAuth code on the MCP server. To do that, you need a proxy code on your MCP server and to create a logging endpoint to use it. The proxy server will allow your MCP server to use Supabase's OAuth server. You'll continue by adding the next code to the MCP server you've created earlier. At the top of your code, after the imports in theserver.js file, you should define the following variables:
const SUPABASE_URL = "
const MCP_SERVER_URL = "";
const SUPABASE_AUTH_URL = `${SUPABASE_URL}/auth/v1`;
if (req.method === 'OPTIONS') condition, add the following proxy code to link your Supabase project:
const OIDC_DISCOVERY_URL = `${SUPABASE_AUTH_URL}/.well-known/openid-configuration`;
if (req.method === "GET" && url.pathname === "/.well-known/openid-configuration") {
const response = await fetch(OIDC_DISCOVERY_URL);
const data = await response.json();
res.writeHead(200, {
"content-type": "application/json",
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Methods": "GET, OPTIONS",
});
res.end(JSON.stringify(data));
return;
}
const OAUTH_DISCOVERY_URL = `${SUPABASE_URL}/.well-known/oauth-authorization-server/auth/v1`;
if (req.method === "GET" && url.pathname === "/.well-known/oauth-authorization-server") {
const response = await fetch(OAUTH_DISCOVERY_URL);
const data = await response.json();
res.writeHead(200, {
"content-type": "application/json",
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Methods": "GET, OPTIONS",
});
res.end(JSON.stringify(data));
return;
}
// OPTIONS /.well-known/oauth-protected-resource/mcp
// GET /.well-known/oauth-protected-resource/mcp
if (req.method === "GET" && (url.pathname === "/.well-known/oauth-protected-resource/mcp" || url.pathname === "/.well-known/oauth-protected-resource")) {
const metadata = {
resource: MCP_SERVER_URL,
authorization_servers: [SUPABASE_AUTH_URL],
// Use standard OIDC scopes. Custom resource scopes are enforced server-side, not by Supabase.
scopes_supported: ["openid", "profile", "email", "phone"],
};
res.writeHead(200, {
"content-type": "application/json",
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Methods": "GET, OPTIONS",
"Access-Control-Allow-Headers": "content-type, MCP-Protocol-Version, mcp-protocol-version, authorization",
});
res.end(JSON.stringify(metadata));
return;
}
Step 4: Implementing the Consent and Login Page
On the OAuth server, you might have noticed a consent page. The goal of this page is to inform the user that they are authorizing the LLM to connect to a database or an external resource. In the next section, you will implement this page by making two steps:- First, create a login page that lets users log in to the app.
- Second, you will create a consent page that allows the logged-in user to communicate with the LLM
npx create-next-app@latest mcp_consent --yes
npm install @supabase/ssr
.env file from your Supabase, which will include the following code:
NEXT_PUBLIC_SUPABASE_URL=YOUR_URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=YOUR_KEY
app/login/page.tsx
The login page:
"use client";
import { useState } from "react";
import { useRouter, useSearchParams } from "next/navigation";
import { createBrowserClient } from "@supabase/ssr/dist/module/createBrowserClient";
export default function LoginPage() {
const [email, setEmail] = useState("");
const [password, setPassword] = useState("");
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const router = useRouter();
const searchParams = useSearchParams();
const supabase = createBrowserClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
);
const handleLogin = async (e: React.FormEvent) => {
e.preventDefault();
setLoading(true);
setError(null);
try {
const { error } = await supabase.auth.signInWithPassword({
email,
password,
});
if (error) {
setError(error.message);
} else {
const redirectTo = searchParams.get("redirect") || "/";
router.push(redirectTo);
router.refresh();
}
} catch (err) {
setError("An unexpected error occurred");
} finally {
setLoading(false);
}
};
const handleSignUp = async (e: React.FormEvent) => {
e.preventDefault();
setLoading(true);
setError(null);
try {
const { error } = await supabase.auth.signUp({
email,
password,
});
if (error) {
setError(error.message);
} else {
setError(null);
alert("Sign up successful! Please check your email to confirm your account.");
}
} catch (err) {
setError("An unexpected error occurred");
} finally {
setLoading(false);
}
};
return (
Authentication
{error && (
{error}
)}
Password reset or other options available upon request.
);
}
// app/api/oauth/decision/route.ts
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
import { NextResponse } from 'next/server'
export async function POST(request: Request) {
const formData = await request.formData()
const decision = formData.get('decision')
const authorizationId = formData.get('authorization_id') as string
if (!authorizationId) {
return NextResponse.json({ error: 'Missing authorization_id' }, { status: 400 })
}
const supabase = createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
{
cookies: {
getAll: async () => (await cookies()).getAll(),
setAll: async (cookiesToSet) => {
const cookieStore = await cookies()
cookiesToSet.forEach(({ name, value, options }) => cookieStore.set(name, value, options))
},
},
}
)
if (decision === 'approve') {
const { data, error } = await supabase.auth.oauth.approveAuthorization(authorizationId)
if (error) {
return NextResponse.json({ error: error.message }, { status: 400 })
}
// Redirect back to the client with authorization code
return NextResponse.redirect(data.redirect_url)
} else {
const { data, error } = await supabase.auth.oauth.denyAuthorization(authorizationId)
if (error) {
return NextResponse.json({ error: error.message }, { status: 400 })
}
// Redirect back to the client with error
return NextResponse.redirect(data.redirect_url)
}
}
// app/oauth/consent/page.tsx
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
import { redirect } from 'next/navigation'
export default async function ConsentPage({
searchParams,
}: {
searchParams: { authorization_id?: string }
}) {
const authorizationId = (await searchParams).authorization_id
if (!authorizationId) {
return Error: Missing authorization_id
}
const supabase = createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
{
cookies: {
getAll: async () => (await cookies()).getAll(),
setAll: async (cookiesToSet) => {
try {
const cookieStore = await cookies()
cookiesToSet.forEach(({ name, value, options }) =>
cookieStore.set(name, value, options)
)
} catch (error) {
// In Server Components, cookie writes can fail during render.
// Route Handlers/Server Actions should handle persistence.
console.warn('Skipping cookie write in Server Component render context', error)
}
},
},
}
)
// Check if user is authenticated
const {
data: { user },
} = await supabase.auth.getUser()
if (!user) {
// Redirect to login, preserving authorization_id
redirect(`/login?redirect=/oauth/consent?authorization_id=${authorizationId}`)
}
// Get authorization details using the authorization_id
const { data: authDetails, error } =
await supabase.auth.oauth.getAuthorizationDetails(authorizationId)
console.log("Auth Details: ", authDetails)
if (error || !authDetails) {
return Error: {error?.message || 'Invalid authorization request'}
}
if ("redirect_url" in authDetails && authDetails.redirect_url && typeof authDetails.redirect_url === "string") {
const redirectUrl = authDetails.redirect_url;
console.log("Redirect URL:", redirectUrl);
return redirect(redirectUrl);
}
if (!("client" in authDetails)) {
return Error: Invalid authorization details format
}
return (
{/* Animated gradient background */}
{/* Main Card Container */}
{/* Gradient border effect */}
{/* Content Card */}
{/* Header Section */}
Review and authorize access to your account
{/* Client Information */}
Application
{authDetails.client.name}
Redirect URI
{authDetails.redirect_uri}
{/* Permissions Section */}
{authDetails.scope && authDetails.scope.length > 0 && (
Requested Permissions
{authDetails.scope.split(" ").map((scope, index) => (
))}
)}
{/* Action Buttons */}
{/* Security Info */}
Your data is protected with industry-standard encryption
)
}
Step 5: Testing the OAuth Implementation with MCP Server Inspector
Since you've implemented the consent page, now you can test it and check the authorization in the MCP Server Inspector. This step will help you see how OAuth works and how to test it with the inspector. First, create a new user in Supabase for login and authentication. After creating the user, you can run the projects by typing the following in different terminals: Run your MCP server:node server.js
npx @modelcontextprotocol/inspector@latest --server-url --transport http
cd mcp_consent
npm run dev
When you click Connect, go to Auth to check your options. The guided OAuth flow will show you a step-by-step guide to how the MCP Server obtains OAuth authorization and will help you debug your code if issues arise. The Check OAuth Flow button lets you connect directly and see the latest result immediately.
For the sake of speed, you can just click on the "Check OAuth Flow". This will redirect you to the login page:
After you log in, you'll get redirected again to the consent page so that you can give consent to the LLM to access your data:
Then you'll be redirected again to the MCP Server and you can check the results of the OAuth flow:
In the next step, you'll harden your MCP Server functions to take your app to the next level by using OAuth for MCP Server.
Step 6: Adding OAuth Security to Your MCP Server Tools
Congrats on implementing your OAuth flow and getting it to work! Now you'll add this flow to your MCP Server tools so it runs only when the user is authenticated. Before updating the tools, you'll write a few helper functions to assist you during the process. First, you'll write a verification token to process every request. Then you'll update the list of MCP server tools to use the verification function instead of implementing it for each function by itself. Inside yourserver.js file, you'll implement a function that verifies the token with Supabase. First, import the Supabase client to use it:
import { SupabaseClient } from "@supabase/supabase-js";
const SUPABASE_PUBLISHABLE_KEY = "YOUR_KEY";
const replyWithTodos = (message, todos) => ({
content: message ? [{ type: 'text', text: message }] : [],
structuredContent: { tasks: todos },
}); //outside the createTodoServer function block
const verifyToken = async (token) => {
if (!token || !token.startsWith("Bearer ")) {
return { isValid: false, error: "Missing or invalid Authorization header" };
}
// Verify token with Supabase
try {
// use supabase client to verify token
const supabase = new SupabaseClient(SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, {
global: {
headers: {
Authorization: token,
},
},
});
const { data: user, error } = await supabase.auth.getUser();
if (error || !user) {
return { isValid: false, error: "Token verification failed" + (error?.message || "") };
}
console.log("Token verified for user:", user);
return { isValid: true, token, user, supabase };
} catch (error) {
console.error("Token verification failed:", error);
return { isValid: false, error: "Token verification failed" + (error?.message || "") };
}
};
/**
* Build WWW-Authenticate header for 401/403 responses
* Per RFC 9728 OAuth 2.1 Protected Resource Metadata specification
*/
function buildWwwAuthenticateHeader(error, errorDescription) {
const resourceMetadataUrl = `${MCP_SERVER_URL}/.well-known/oauth-protected-resource`
let header = `Bearer resource_metadata="${resourceMetadataUrl}"`
if (error) {
header += `, error="${error}"`
}
if (errorDescription) {
header += `, error_description="${errorDescription}"`
}
return header
}
function returnAuthErrorResponse(resOrMessage, error = "unauthorized", errorDescription = "Missing or invalid authorization token.") {
const wwwAuthenticate = buildWwwAuthenticateHeader(error, errorDescription);
if (resOrMessage && typeof resOrMessage.writeHead === "function") {
resOrMessage.writeHead(401, {
"content-type": "application/json",
"Access-Control-Allow-Origin": "*",
"WWW-Authenticate": wwwAuthenticate,
});
resOrMessage.end(JSON.stringify({ error, error_description: errorDescription }));
return;
}
const message = typeof resOrMessage === "string" && resOrMessage.length > 0
? resOrMessage
: errorDescription;
return {
content: [{ type: "text", text: message }],
isError: true,
statusCode: 401,
_meta: {
"mcp/www_authenticate": wwwAuthenticate,
},
};
}
function returnErrorResponse(message) {
return {
content: [
{
type: "text",
text: message
}
],
isError: true
};
}
Step 7: Updating the MCP Server Function to Handle the Authentication
After you've built the proxy to handle authentication requests, you need to update the MCP server functions and metadata to indicate whether the tool can be used with or without authentication. Here you'll add two main things: server.registerTool(
"list_todos",
{
title: "List todos",
description: "Lists all todo items.",
_meta: {
"openai/outputTemplate": "ui://widget/todo.html",
"openai/toolInvocation/invoking": "Listing todos",
"openai/toolInvocation/invoked": "Listed todos",
},
securitySchemes: [
{ type: "oauth2", scopes: ["todos.read"] }
],
"annotations": {
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false,
}
},
async (meta) => {
const authHeader = meta.requestInfo.headers?.authorization;
const authResult = await verifyToken(authHeader);
if (!authResult?.isValid) {
return returnAuthErrorResponse(authResult?.error);
}
const { data, error } = await authResult.supabase
.from("todos")
.select("*")
.eq("user_id", authResult.user.user.id)
.order("created_at", { ascending: false });
if (error) {
console.error("Error listing todos:", error);
return returnErrorResponse(error.message);
}
return replyWithTodos(null, data ?? []);
}
)
- Updated the metadata to have a security schema that tells the MCP server to request authentication when invoking these tools.
-
Added an annotation, which helps the LLM model know how this function will perform. The annotations declare three types of changes that the tool can make:
- Read Only Hint: tells the LLM whether the tool is read-only and only shows data
- Open World Hint: tells the LLM whether the tool can access external data, websites, or the internet.
- Destructive Hint: tells the LLM if this is a destructive function, like deleting data permanently for the user
- Then, in the function itself, you retrieved the metadata from the callback and verified the token using the Supabase helper function. After that, you used the basic Supabase functions to retrieve the data and any errors that might occur.
const { data, error } = await authResult.supabase
.from("todos")
.select("*")
.eq("user_id", authResult.user.user.id)
.order("created_at", { ascending: false });
if (error) {
console.error("Error listing todos:", error);
return returnErrorResponse(error.message);
}
insert or update.
For the other functions, you can follow the same principles and use the same code. The only change is that first you get the data, then the metadata in the callback function:
server.registerTool(
"add_todo",
{
title: "Add todo",
description: "Creates a todo item with the given title.",
inputSchema: addTodoInputSchema,
_meta: {
"openai/outputTemplate": "ui://widget/todo.html",
"openai/toolInvocation/invoking": "Adding todo",
"openai/toolInvocation/invoked": "Added todo",
},
securitySchemes: [
{ type: "oauth2", scopes: ["todos.write"] }
],
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true,
}
},
async (args, meta) => {
const authorizationHeader = meta.requestInfo.headers?.authorization;
console.log("Authorization header:", authorizationHeader);
const authResult = await verifyToken(authorizationHeader);
console.log("Auth result:", authResult);
if (!authResult?.isValid) {
return returnAuthErrorResponse(authResult?.error);
}
const title = args?.title?.trim?.() ?? "";
if (!title) return returnErrorResponse("Missing title.");
let { data, error } = await authResult.supabase
.from("todos")
.insert({ title, user_id: authResult.user.user.id })
.select("*");
if (error) {
console.error("Error adding todo:", error);
return returnErrorResponse(error.message);
}
return replyWithTodos(`"${title}"`, data);
}
);
server.registerTool(
"complete_todo",
{
title: "Complete todo",
description: "Marks a todo as done by id.",
inputSchema: completeTodoInputSchema,
_meta: {
"openai/outputTemplate": "ui://widget/todo.html",
"openai/toolInvocation/invoking": "Completing todo",
"openai/toolInvocation/invoked": "Completed todo",
},
securitySchemes: [
{ type: "oauth2", scopes: ["todos.write"] }
],
"annotations": {
"readOnlyHint": false,
"openWorldHint": false,
"destructiveHint": true,
}
},
async (args, meta) => {
const authorizationHeader = meta.requestInfo.headers?.authorization;
const authResult = await verifyToken(authorizationHeader);
if (!authResult?.isValid) {
return returnAuthErrorResponse(authResult?.error);
}
const id = args?.id;
if (!id) return replyWithTodos("Missing todo id.");
const { data, error } = await authResult.supabase
.from("todos")
.update({ completed: true })
.eq("id", id)
.eq("user_id", authResult.user.user.id)
.select("*");
if (error) {
console.error("Error completing todo:", error);
return returnErrorResponse(error.message);
}
if (!data || data.length === 0) {
return replyWithTodos(`Todo ${id} was not found.`);
}
return replyWithTodos(`Completed "${data[0].title}".`, data);
}
);
Step 8: Testing the Server with Supabase:
To do this, you can follow the same steps as in "Testing the OAuth implementation with MCP Server Inspector." But as an extra point, keep an eye on your database table in the Supabase UI, where you can see the added and updated todos. Then you can check the tools, test your todos, and even use ngrok to test them in the ChatGPT UI.How to Deploy your MCP Server to DigitalOcean
Since you have your MCP server running and working well, you can now deploy it to DigitalOcean using their App service. First, upload your code to GitHub and commit it with the following command:gh repo create todo_mcp_server --private --source=. --remote=upstream
git push
Choose the source as GitHub:
Then you need to select your repository and your branch. Write the source directories as: / and mcp_consent. You're doing this because you'll be running two apps: the MCP Server and the consent and login page frontend.
Next, enable auto-deploy if you want the app to update whenever you push your code to GitHub:
Since we've created two source directories, you'll have two apps and will have to manage them separately.
You'll use the MCP server in the first app and the frontend for the second app. For that reason, you'll update the network to have the server under the /server route:
And you'll downsize the CPU to minimize the cost for this demo:
You can update the size later based on your needs for the app.
As for the last step here, you'll update the run command to node server.js to ensure the app is running correctly.
For the frontend project, you'll have to click on the second app, update the inputs as well, and add the environment variables:
First, you can downsize the app:
Update the build and run commands for the Next js server:
Then you can check the route of this web app and set it as the main one:
At the end, you need to add the .env variables from your .env file to the project. You can copy and paste them directly from your mcp_const/.env file to the project.
After setting them up, you can create and run the app, which will generate a public URL from DigitalOcean that you can use in the ChatGPT UI again to test it and run the project.
Before adding the project to test it in ChatGPT, you need to update the consent page URL in Supabase from here.
Instead of havinglocalhost:300, you can add the link from your DigitalOcean account.
At this point, you can test the server with your DigitalOcean by using the following links:
- YOUR_DIGITAL_OCEAN.com/server/mcp
- YOUR_DIGITAL_OCEAN.com/login
- YOUR_DIGITAL_OCEAN.com/oauth/consent
How to Publish Your ChatGPT App
After running your app, you need to host it. You can simply upload it to GitHub and host it on DigitalOcean as a JavaScript app. You can get the URL from DigitalOcean, then go to your OpenAI dashboard, verify yourself as a company or a solo developer, and upload the file there. To publish your app to ChatGPT, you'll need to provide the following information:- App Info: the basic information about your app, including the logo, description, a video demo, website, support, privacy policy, and terms of service URLs (plus a few more details about monetizing your app if you have done that).
- MCP Server: the links to your MCP server, the tools you have, and how you'll use them, plus a verification token for your URL that you'll need to add to your project as a path.
-
Testing: you'll need to provide at least 5 test cases for your MCP server so OpenAI can test its functionality. They require you to have coverage over all the major use cases that you intend to support and include all information required to successfully run the test case.
In the tests you share:
- Scenario: where you describe the use case to test (for example, “Research flights”, “Create a slideshow”, “Find a hiking trail”).
- User prompt: The exact prompt or interaction you should conduct to begin the test.
- Tool triggered: Which tools should be called? You have already implemented them.
- Expected output: The output or experience you should expect to receive back from the MCP server.
- Then you share the negative cases with the same examples.
- Screenshots: App screenshots for the directory. You can use this public Figma to help you with your design. Here, you should upload 1–4 screenshots of your app widget UI in PNG or JPG format, each with a width of 706px and a height of 400–860px (at least one must be 2× retina quality). The first three screenshots are publicly visible in install views across all screen sizes and locales. Ensure the images show only your widget UI – no ChatGPT interface, user prompts, model responses, or embedded text.
- Global: shows the text and localization for your app. You can also select specific countries to publish to.
- Submit: This requires you to write the release notes and run a few compliance checks on your app.