mcp server - freeCodeCamp.org

How to Create a Marketing Landing Page Using shadcn/ui

Vaibhav Gupta — Fri, 31 Jul 2026 11:01:41 +0000

Most marketing landing pages start with the same problem: you're staring at a blank screen and rebuilding sections you've already created countless times.

A hero section, feature grid, testimonials, pricing, FAQ, and footer are common building blocks, yet developers often spend hours recreating them for every new project.

In this guide, you'll learn how to build a modern marketing landing page using Next.js, shadcn/ui, Tailwind CSS, and reusable Shadcn blocks. Instead of building every section from scratch, you'll assemble a production-ready page, customize it to match your brand, and finish with a foundation that's ready for real-world projects.

Prerequisites
What Are We Building?
Project Setup with Base UI Using the Shadcn Preset
Two Ways to Build Your Marketing Landing Page
Option 1: Build Using the CLI
Option 2: Build Using the MCP Server
How to Optimize Your Landing Page
How to Expand Your Marketing Website
Live Preview:
Conclusion

Prerequisites

Before you start, make sure you have:

Node.js 18 or higher installed
shadcn/ui initialized in your project (npx shadcn@latest init)
Basic knowledge of React and TypeScript

If you haven't initialized shadcn/ui yet, run npx shadcn@latest init in your project root and follow the prompts before continuing.

What Are We Building?

In this tutorial, we'll build a modern marketing landing page using production-ready blocks from Shadcn Space. Instead of designing and developing every section from scratch, we'll assemble a complete landing page using reusable shadcn/ui blocks and customize them to fit our brand and product.

You can use the same approach to create landing pages for SaaS products, AI tools, startups, agencies, developer tools, portfolios, and many other types of websites. Since every block is built with React, Tailwind CSS, and shadcn/ui, you have full control over the code and can easily modify the content, layout, and styling.

Why Build with Shadcn Space?

Creating a professional marketing website typically involves designing multiple sections that work together to tell your product's story and guide visitors to take action.

But instead of building every section from scratch, you can start with production-ready blocks that are easy to customize.

This lets you build marketing websites faster with reusable blocks (and you can also mix and match blocks to create unique page layouts). It also gives you full ownership of your clean React and Tailwind CSS code. And overall, you save development time without sacrificing flexibility.

Sections We'll Build

We'll build our marketing landing page using the following sections:

Hero section with a compelling headline, call-to-action, and trusted-by logos.
Features section to highlight your product's key capabilities.
Product Showcase & Benefits section to demonstrate your product and communicate its value.
Testimonials section to build credibility with customer feedback.
Pricing section to present your plans clearly.
FAQ section answers common questions and reduces friction.
Call-to-Action section to encourage visitors to get started.
Footer with navigation and important links.

Final Page Structure

Our landing page will have this structure:


  {/* 1. Hero section + Trusted by / Logo cloud */}
  

  {/* 2. Features section */}
  

  {/* 3. Product showcase & Benefits */}
  

  {/* 4. Testimonials */}
  

  {/* 5. Pricing section */}
  

  {/* 6. FAQ section */}
  

  {/* 7. Call-to-action section */}
  

  {/* Footer */}

Each section will be installed from the Shadcn Space registry and customized directly inside our project. By the end of this tutorial, you'll have a fully responsive marketing landing page built with Next.js, Tailwind CSS, and shadcn/ui that you can adapt for your own product or business.

Project Setup with Base UI Using the Shadcn Preset

Since Shadcn Space blocks are built using Base UI primitives, we'll create our project using the Base UI preset instead of the default Radix setup.

This ensures that our landing page uses the same foundation as the blocks we're going to install.

1. Create the Project with Base UI

Run the following command:

pnpm dlx shadcn@latest init --preset b0 --template next

This command does a few important things:

Creates a Next.js project
Configures Tailwind CSS
Sets up Base UI as the component foundation
Uses the Nova style preset
Configures Lucide icons
Uses Inter font
Applies neutral theme tokens

You now have a Base UI-powered Next.js project ready for building your landing page.

2. Add the Shadcn Space Registry

Open your components.json and add the following registry configuration:

{
  "registries": {
    "@shadcn-space": {
      "url": "https://shadcnspace.com/r/{name}.json",
    }
  }
}

This tells the CLI where to fetch components and blocks from the registry.

For more information about how to use it in your project, check out the docs.

Two Ways to Build Your Marketing Landing Page

Now that your project is set up with shadcn/ui, it's time to start building the marketing landing page.

You can install production-ready blocks directly into your project in two different ways:

Using the CLI
Using the MCP Server inside your AI-powered editor

Both approaches install the actual React and Tailwind CSS source code into your project, giving you complete control over customization. The only difference is how you discover and install the blocks.

Option 1: Build Using the CLI

The CLI is the fastest way to browse the registry and install individual blocks into your project. It gives you full control over which sections you want to use and how you customize them.

Step 1: Browse Marketing Blocks

Visit the block registry and explore the available marketing blocks.

Let's review the sections we'll use for this tutorial:

Hero section with a call-to-action and trusted-by logos
Features section
Product showcase & benefits section
Testimonials section
Pricing section
FAQ section
Call-to-action section
Footer

Choose the blocks that best match the design and style of your website. Since every block is fully customizable, you can easily update the content, colors, spacing, and layout to match your brand.

In the following sections, we'll install each block and customize them.

Step 2: Install Selected Blocks

Once you find a block you like, install it using the CLI:

npx shadcn@latest add @shadcn-space/{block-name}

Each command downloads the block, places it inside components/shadcn-space/blocks, and installs the required dependencies.

Now your folder might look like this:

components/
  shadcn-space/
    blocks/
      about-us-section-01/
      hero-01/
      features-01/
      pricing-01/
      testimonial-01/
      faq-01/
      cta-01/
      footer-01/

Note: I've used the first block from each section in this tutorial. You can choose any other shadcn block that suits best according to your needs.

Step 3: Add a Hero Section

Every great marketing landing page starts with a strong hero section. It's the first thing visitors see, so it should clearly communicate what your product does, who it's for, and encourage users to take action.

Instead of building the section from scratch, we'll install a production-ready Hero block and customize it to match our landing page.

1. Install the Hero Block

Run the following CLI command to add the Hero block to your project:

npx shadcn@latest add @shadcn-space/hero-01

The CLI will automatically download the Hero block source code, add the component to your project, and install any required dependencies.

After the installation completes, you should see the following directory structure:

components/
  shadcn-space/
    blocks/
      hero-01/
        index.tsx

You can now open the component and customize the heading, description, call-to-action buttons, images, and other content to match your product and branding.

2. Understand the Hero Block Structure

Once the installation is complete, open the Hero block located at:

components/shadcn-space/blocks/hero-01/index.tsx

You'll see a component similar to the following:

import HeroSection from "@/components/shadcn-space/blocks/hero-01/hero";
import type { NavigationSection } from "@/components/shadcn-space/blocks/hero-01/header";
import Header from "@/components/shadcn-space/blocks/hero-01/header";
import BrandSlider, { BrandList } from "@/components/shadcn-space/blocks/hero-01/brand-slider";
import type { AvatarList } from "@/components/shadcn-space/blocks/hero-01/hero";

export default function AgencyHeroSection() {
  const avatarList: AvatarList[] = [...];
  const navigationData: NavigationSection[] = [...];
  const brandList: BrandList[] = [...];

  return (
    
      
      
        
        
      
    
  );
}

What Should You Notice?

Before making any changes, take a moment to understand how the block is organized. Rather than being a single large component, it's composed of smaller, reusable components that work together.

In this example:

The Header component renders the navigation and receives its menu items through the navigationData array.
The HeroSection component contains the main headline, description, call-to-action buttons, and social proof, while the avatarList provides the data displayed in the hero.
The BrandSlider component displays the company logos using the brandList array.

This separation keeps the code modular and makes each part of the landing page easier to customize or replace independently.

Why This Matters?

Because the block is copied directly into your project, you're working with standard React components instead of a compiled package. Every file is fully editable, allowing you to understand how the section is built and modify it to suit your own requirements.

For example, you can update the navigation links, replace the placeholder content with your own branding, add additional sections, integrate custom functionality, or adjust the styling using Tailwind CSS classes. Since everything lives inside your codebase, you're free to restructure the component however you like without being locked into predefined APIs or abstractions.

3. Render the Hero Section

Now that the Hero block has been installed, it's time to display it on the page.

Import the component into your app/page.tsx file:

import AgencyHeroSection from "@/components/shadcn-space/blocks/hero-01";

export default function Page() {
  return (
    
  );
}

Save the file and start your development server if it isn't already running. When you open the application in your browser, you'll see the Hero section rendered as the first part of your marketing landing page.

With the Hero section in place, we've completed the first building block of our landing page. Next, we'll continue by adding the remaining sections to create a complete marketing website.

Install the Remaining Blocks

Now that you've added and rendered the Hero section, let's install the remaining blocks required for our marketing landing page.

Run the following command to install all the remaining sections at once:

npx shadcn@latest add @shadcn-space/feature-01 @shadcn-space/about-us-section-01 @shadcn-space/testimonial-01 @shadcn-space/pricing-01 @shadcn-space/faq-01 @shadcn-space/cta-01  @shadcn-space/footer-01

Note: If you're using Windows Command Prompt or PowerShell, run the command on a single line instead of using \ for line continuation.

After the installation is complete, update your app/page.tsx by importing the newly added blocks and rendering them in the following order:

import AgencyHeroSection from "@/components/shadcn-space/blocks/hero-01";
import AboutAndStats01 from "@/components/shadcn-space/blocks/about-us-01";
import Feature01 from "@/components/shadcn-space/blocks/feature-01";
import Pricing from "@/components/shadcn-space/blocks/pricing-01/pricing";
import Testimonials from "@/components/shadcn-space/blocks/testimonial-01/testimonial";
import Faq from "@/components/shadcn-space/blocks/faq-01/faq";
import CTA from "@/components/shadcn-space/blocks/cta-01/cta";
import Footer from "@/components/shadcn-space/blocks/footer-01/footer";


export const metadata = {
  title: "Acme Agency – Innovative Digital Solutions",
  description:
    "We craft immersive digital experiences for bold brands. Explore our services, pricing, and success stories.",
};


export default function Page() {
  return (
    
      {/* 1. Hero section + Trusted by / logo cloud */}
      


      {/* 2. Features section */}
      


      {/* 3. Product showcase & Benefits section (Using About/Stats as a placeholder for these) */}
      


      {/* 4. Testimonials */}
      


      {/* 5. Pricing section */}
      


      {/* 6. FAQ section */}
      


      {/* 7. Call-to-action section */}
      


      {/* Footer */}
      
    
  );
}

That's it! Your complete marketing landing page is now assembled. You can start customizing the content, images, colors, and layout of each section to match your product and brand.

Customize the Marketing Landing Page

At this point, the overall structure of your marketing landing page is complete. The next step is to personalize each section so it reflects your product, brand, and messaging instead of the default placeholder content.

One of the biggest advantages of working with reusable React components is that every section can be customized independently. You can update the content, replace images, adjust layouts, and refine the styling without rebuilding the page from scratch.

The following examples show how the default blocks can be transformed into a polished marketing website.

Customize the Hero Section

The Hero section is the first thing visitors see, so it's the most important place to communicate your product's value. Replace the placeholder headline, supporting text, call-to-action buttons, and trusted brand logos with content that represents your own business.

Before:

After:

Notice how the customized version immediately establishes the product's identity through updated messaging, branding, imagery, and call-to-action buttons.

Customize the Features Section

The Features section should explain what your product offers and why it stands out. Replace the sample feature cards with capabilities that highlight your product's most valuable functionality.

Before:

After:

Updating the feature titles, descriptions, and icons makes the section more relevant to your audience while reinforcing your product's key selling points.

Customize the Pricing Section

Your pricing section should clearly communicate the plans you offer and help visitors choose the option that best fits their needs. Replace the default plans, pricing, feature lists, and button labels with information that matches your business model.

Before:

After:

A customized pricing section builds trust by presenting accurate information while making it easier for potential customers to compare plans.

Customize the FAQ Section

The FAQ section is a great opportunity to answer common questions before visitors contact your team. Replace the placeholder questions with answers related to your product, pricing, integrations, support, or onboarding process.

Before:

After:

Tailoring the FAQ to your product helps reduce uncertainty, improves the user experience, and can answer many questions before a customer reaches out.

The Result

With just a few content updates, the default blocks evolve into a professional marketing landing page tailored to your brand. Since every section is built with reusable React components, you can continue refining the design, adjusting layouts, and adding new content as your product grows without changing the overall page structure.

Option 2: Build Using the MCP Server

If you prefer a faster workflow, you can use the MCP Server to generate your landing page directly inside your editor. Instead of manually browsing and installing individual blocks, you simply describe the page you want to build, and the MCP Server assembles an initial version for you.

The MCP Server works with supported editors like Antigravity, VS Code, Cursor, Windsurf, and other MCP-compatible editors.

Step 1: Install the MCP Server

Quick Installation:

The fastest way to get started. Choose your package manager and run the command corresponding to your client:

For Claude Code:

claude mcp add shadcnspace-mcp -- npx -y shadcnspace-mcp@latest

For Others:

npx shadcnspace-cli install

Replace with cursor, antigravity, vscode, or windsurf.

Manual Installation For VS Code:

{
  "servers": {
    "shadcnspace-mcp": {
      "command": "npx",
      "args": ["-y", "shadcnspace-mcp@latest"]
    }
  }
}

Open .vscode/mcp.json.
Click Start next to the Shadcn Space MCP server

For a detailed guide, follow the MCP Server documentation to install it for your preferred editor.

Once the installation is complete, restart your editor to enable the MCP connection.

Step 2: Open the AI Chat

Open the AI chat panel inside your editor and describe the landing page you'd like to create.

For example:

Create a modern marketing landing page for an AI SaaS product.

Use Shadcn Space blocks and include:

- Hero section
- Features section
- Product showcase & benefits
- Testimonials
- Pricing
- FAQ
- Call-to-action
- Footer

Use a clean, modern, and responsive design.

Feel free to replace the product description with your own and customize as you like.

Step 3: Generate the Landing Page

After receiving your prompt, the MCP Server analyzes your requirements and selects the most suitable blocks for your landing page. It automatically assembles the page using a combination of reusable sections, giving you a working layout in just a few moments.

The generated sections are added directly to your project as standard React components. Since everything is real source code, you can customize every part of the page: update the content, replace images, modify the layout, adjust spacing, or restyle components using Tailwind CSS.

The MCP Server simply speeds up the initial setup, while giving you complete control over the final implementation.

How to Optimize Your Landing Page

Building a visually appealing landing page is only the first step. Before publishing your website, it's worth spending some time optimizing it for performance, search engines, and user experience.

A fast, responsive landing page not only feels more polished but also helps improve engagement and conversion rates. Fortunately, Next.js provides several built-in features that make these optimizations straightforward.

Optimize Images with Next.js

Images are often the largest assets on a marketing website, so optimizing them can significantly improve loading performance. If you're using Next.js, prefer the built-in next/image component instead of the standard HTML image tag. It automatically serves appropriately sized images, supports modern image formats, and reduces layout shifts as the page loads.

Before adding screenshots or illustrations to your project, make sure they're compressed and sized appropriately. Well-optimized images create a smoother browsing experience across desktop and mobile devices while also contributing to better Core Web Vitals.

Improve SEO for Your Landing Page

A well-designed landing page is only effective if people can discover it. Search engine optimization starts with creating meaningful content that clearly communicates what your product offers. Choose a descriptive page title, write a concise meta description, and organize your content using logical headings.

Your primary keyword should appear naturally throughout the page without forcing it into every paragraph. Focus on writing for your audience first, then structure the content in a way that search engines can easily understand. Combining valuable content with a clear page hierarchy gives your landing page the best chance of ranking for relevant searches.

Add Metadata and Open Graph Images

When someone shares your landing page on social media or in a messaging application, the preview is generated from your page's metadata. Configuring Open Graph and Twitter metadata allows you to control the title, description, and preview image that appear when your website is shared.

A custom preview image that reflects your branding makes your links look more professional and can encourage more people to click through. Taking a few minutes to configure these settings helps create a more polished experience whenever your content is shared online.

Optimize Performance

Performance plays a major role in how visitors perceive your website. A page that loads quickly feels more responsive and encourages users to continue exploring your content. As you customize your landing page, keep unnecessary JavaScript to a minimum, optimize static assets, and avoid loading resources that aren't immediately needed.

Even small improvements, such as reducing image sizes or simplifying animations, can noticeably improve loading speed. Before deploying your project, test the page under different network conditions to ensure it performs well for all visitors.

Improve Core Web Vitals

Core Web Vitals are Google's metrics for measuring real-world user experience. They evaluate how quickly your main content appears, how responsive the page feels during interactions, and whether elements remain stable as the page loads. Monitoring these metrics throughout development helps identify potential issues before they affect users.

Tools such as Lighthouse and PageSpeed Insights provide detailed reports that can help you improve loading performance and responsiveness. A landing page with strong Core Web Vitals not only creates a better experience for visitors but can also contribute to improved search rankings.

How to Expand Your Marketing Website

A landing page is often just the beginning of a complete marketing website. As your product grows, you'll likely need additional pages that provide more information, improve navigation, and create a better experience for your visitors. Common additions include Blog, Blog Details, Pricing, FAQ, Changelog, Contact, Integration, Error, and About Us pages.

Building these pages with a consistent design system helps maintain a unified look and feel across your entire website while reducing development time. Reusing layouts and components also makes your project easier to maintain as it evolves.

If you're looking to expand your website beyond a single landing page, explore the collection of production-ready Shadcn website pages, built with React, Next.js, Tailwind CSS, and shadcn/ui.

Live Preview:

Conclusion

In this tutorial, we built a complete marketing landing page using Next.js, shadcn/ui, Tailwind CSS, and reusable Shadcn Space blocks. Starting from a fresh project, we assembled a production-ready page by combining sections such as the Hero, Features, Product Showcase, Testimonials, Pricing, FAQ, Call-to-Action, and Footer.

Because every block is added as standard React source code, you're free to customize the content, layout, styling, and functionality to match your own product and branding. Whether you're building a SaaS application, a startup website, an AI product, an agency site, or a developer tool, the same approach can be adapted to your requirements.

A marketing landing page is just the foundation of your online presence. As your product grows, you can continue expanding your website with additional marketing pages while maintaining a consistent design system and development workflow.

I hope this guide has helped you understand how to quickly build a modern, responsive marketing landing page using reusable components. Feel free to experiment with different block combinations, personalize the design, and create a website that best represents your product.

Appreciation: I wrote this article with the help of Mihir Koshti (Sr. Full Stack Developer) – Connect on LinkedIn.

How to Build Your Own MCP Server and Publish Your ChatGPT App with Supabase Auth and DigitalOcean

Abdurrahman Rajab — Thu, 09 Jul 2026 16:04:02 +0000

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?
- What Can You Do with an MCP Server?
Level 1: How to Build Your Own MCP Server
How to Test Your MCP Server
Level 2: How to Build the UI
How to Test Your ChatGPT App
Level 3: How to Add Supabase (Auth and Database) to the MCP Server
How to Deploy Your MCP Server to DigitalOcean
How to Publish Your ChatGPT App
What to Do Next
Acknowledgments
References

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 -y to create a JavaScript package file and add the packages to the project with ES6 support.
Initialize Git with git init in 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 .gitignore file and add the node_modules to 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:
- git add .
- git commit -m "init project"

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, `http://${req.headers.host ?? "localhost"}`);

    res.writeHead(404).end("Not Found");

});

httpServer.listen(port, () => {
    console.log(`Todo MCP server listening on http://localhost:${port}, 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:

git add .
git commit -m "feat: add MCP todo server"

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, `http://${req.headers.host ?? '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 http://localhost:${port}${MCP_PATH}`,
    );
});

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:

git add .
git commit -m "feat: add MCP server functions"

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 http://localhost:8787/mcp. 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 http://localhost:8787/mcp --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

Then inside

tag, you should add the following:

      Todo list

You can see it’s just simple HTML tags that allow you to have the header, form with an input, and an unordered list with 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 the tag.

First, you need to identify the elements by selecting the HTML tag IDs you provided to them in the HTML code:

const listEl = document.querySelector("#todo-list");
const formEl = document.querySelector("#add-form");
const inputEl = document.querySelector("#todo-input");

Then you can use these elements to extract data from the ChatGPT response using some special 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:

window.openai.callTool
window.openai?.toolOutput

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 ?? [])];

You can then loop through all tasks to add them to the list element:

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);
    });
};

You can call this function to loop through the tasks from the OpenAI result and print them on the screen.

You can add the update function to update tasks to be completed with the following code:

const updateFromResponse = (response) => {
    if (response?.structuredContent?.tasks) {
        tasks = response.structuredContent.tasks;
        render();
    }
};

In the code above, you received a new response from the AI and an update form via the function. This function will get the todos list from the LLM and re-render the HTML to show the todos:

const handleSetGlobals = (event) => {
    const globals = event.detail?.globals;
    if (!globals?.toolOutput?.tasks) return;
    tasks = globals.toolOutput.tasks;
    render();
};

In the next code block, you'll handle the form response in the updateFormResponse function and set event listeners to update the code when changes are detected:


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 the style 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;
      }

Now you can commit your code to Git and track it in the tree:

git add .
git commit -m "feat: add MCP server UI"

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;

To use the signature function, you can use the following simple code at the top of your file, which will read the HTML file you created:

import { readFileSync } from "node:fs";

const todoHtml = readFileSync("public/todo-widget.html", "utf8");

And this resources registration code in the 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 },
            },
        ],
    })
);

In the above code, you've added the following parameters:

The name of the resource
The sources of the resource or the template as a string

You kept the config empty to simplify the example

You only used the contents of the callback to show the information about the resources with the following details:

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",
        },

So the _meta tag in your tools functions will look like the following:

    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();
        },
    );

Now you can commit your code to Git and track it in the tree:

git add .
git commit -m "feat: add _meta outputTemplate tag to MCP server tools"

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

Then run your server through ngrok to enable online access, since you need OpenAI servers to be able to access your local machine:

ngrok http 8787

Note: You need to have an ngrok account and log in to it via the CLI.

To add your resources to ChatGPT, you need to enable dev mode and add it as a connector:

Click on your profile in the ChatGPT UI
Click on Apps
Click on Advanced settings to create your own app

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 mcp slash
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();

At the end, set the table to row-level security. This allows related users to see their data:

-- 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);

Since your database is now ready, you can integrate authentication with your server. First, you need to authenticate the server, get the token, and use it on the server. Then you can test the app again.

To authenticate, you need to implement the following endpoints on your server (and add your own information in place of the example info):

GET: https://your-mcp.example.com/.well-known/oauth-protected-resource
OAuth 2.0 metadata: https://auth.yourcompany.com/.well-known/oauth-authorization-server
OpenID Connect metadata: https://auth.yourcompany.com/.well-known/openid-configuration

The OAuth-protected resource communicates with the server about how to use and register the tools, how to run them, and what to call them. The other two endpoints share the related metadata from the server

You'll need to implement those endpoints on your server and use them as a proxy to fetch data from Supabase, since it will be your main auth server.

Step 2: Enabling the MCP Server to Connect with Supabase Auth

For this, you need to do the following:

Enable the OAuth server at Supabase and enable the dynamic registration of tools
Implement a page for login to use for OAuth permission

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 the server.js file, you should define the following variables:

const SUPABASE_URL = "https://YOURPORJECT.supabase.co";
const MCP_SERVER_URL = "http://localhost:8787/mcp";
const SUPABASE_AUTH_URL = `${SUPABASE_URL}/auth/v1`;

Note: Don't forget to enter your own project URL for the Supabase URL. You can find it in the Supabase UI by clicking Connect at the top of the page.

Inside the createServer function and after the 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;
}

Then you can add this code for the OAuth authorities server:

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;
}

Then add this code for the well-known server:

// 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;
}

By adding the previous code snippets, you've implemented a proxy server that fetches data from Supabase and relays it to the MCP protocol as if it were your own server.

Now you can commit your code to Git and track it in the tree:

git add .
git commit -m "feat: add supabase proxy server"

Since you've implemented your proxy server, you can use authentication and authorization from your MCP server to retrieve data in your tools.

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

You'll start by creating a new Next.js server, which gives you more flexibility when working with pages.

You can create your NextJS app with the command:

npx create-next-app@latest mcp_consent --yes

Navigate to the mcp_consent folder and add Supabase:

npm install @supabase/ssr

Add the current state of the project to your Git tracker by writing the following:

git add .
git commit -m "init nextjs project"

Add .env file from your Supabase, which will include the following code:

NEXT_PUBLIC_SUPABASE_URL=YOUR_URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=YOUR_KEY

Now you can create a login page in the next path:

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}
                    
                )}


                
                    
                        
                            Email address
                        
                         setEmail(e.target.value)}
                            className="mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-blue-500 focus:border-blue-500 text-black"
                            placeholder="you@example.com"
                        />
                    


                    
                        
                            Password
                        
                         setPassword(e.target.value)}
                            className="mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-blue-500 focus:border-blue-500 text-black"
                            placeholder="••••••••"
                        />
                    


                    
                        
                        
                    
                


                
                    
                        Password reset or other options available upon request.
                    
                
            
        
    );
}

The OAuth decision page:

// 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)
    }
}

The OAuth Consent page:

// 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 */}
                        
                            
                                
                                    
                                
                            
                            Authorization Required
                            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) => (
                                        
                                            
                                            {scope}
                                        
                                    ))}
                                
                            
                        )}

                        {/* Action Buttons */}
                        
                            

                            

                            
                        

                        {/* Security Info */}
                        
                            
                            Your data is protected with industry-standard encryption
                        
                    
                
            
        
    )
}

Now you can add the current state of the project to your Git tracker by writing the following:

git add .
git commit -m "feat: add consent page"

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.

Go to: https://supabase.com/dashboard/project/_/auth/users
(Auth -> users from the UI)
Click Add User -> Create a new user, then add the new user email and password.

After creating the user, you can run the projects by typing the following in different terminals:

Run your MCP server:

node server.js

Open your inspector:

npx @modelcontextprotocol/inspector@latest --server-url http://localhost:8787/mcp --transport http

Run the Next.js project to get access to the consent page:

cd mcp_consent
npm run dev

When you run the inspector, you can connect to your MCP Server on the left and navigate to Auth on the top tab. This will show you the authentication flow to test and run.

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 your server.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";

Then add the Supabase publishable key to use it in the client at the top of the server:

const SUPABASE_PUBLISHABLE_KEY = "YOUR_KEY";

And update the reply todos list to get an argument of todos, instead of the in-memory array.

const replyWithTodos = (message, todos) => ({
    content: message ? [{ type: 'text', text: message }] : [],
    structuredContent: { tasks: todos },
}); //outside the createTodoServer function block

Then you'll need to create a helper function to verify the user tokens:

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 || "") };
    }
};

In this function, you get the token as a string, check Supabase, and return an error if the token isn't provided. If it's correct, you return the token, user data, and Supabase client.

After this, you need to have a helper function to adhere to MCP Server specs:

/**
 * 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
    };
}

In these helper functions, you create unique functions for errors and the OAuth error return function. At the same time, you define the OAuth-protected resources discovery specs.

Add the current state of the project to your Git tracker by writing the following:

git add .
git commit -m "feat: add helper functions"

Now you can apply them to your MCP Server tools, making them easier to read.

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:

The security schema.
The logic for the function to handle.

   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 ?? []);
        }
    )

In this code, you've done the following:

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.

You can get the authorization from the metadata in the callback function itself.

In the previous function, you used the Supabase client to access the todos table, select all columns where the user_id condition is met, and order them by creation time. If the Supabase client returns an error, you return an error. Here's the code snippet that relates to Supabase:

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);
}

For the other function, you have the same logic applied, yet instead of select, you'll use either 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);
        }
    );

Here's the updated function code:

    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);
        }
    );

By applying this, you already have a fully functioning MCP server connected to your Supabase, and you can rely on it to run.

Add the current state of the project to your Git tracker by writing the following:

git add .
git commit -m "feat: update tools to use database"

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

This command creates a new repo on GitHub, sets your stream to GitHub, and pushes the current branches to GitHub.

Then log in to your DigitalOcean account and go to Apps (https://cloud.digitalocean.com/apps).

Click on Create app:

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.

After uploading and updating your project, you can wait for OpenAI to review your project and get the results from them.

What to Do Next

You now have the basic knowledge you need to explore MCP servers and ChatGPT apps. You can dive deeper by reading the documentation and checking the related tools and platforms for building apps like Skybridge.

If you liked this tutorial, you can follow me on Twitter or YouTube and run the full project demo script on GitHub.

Acknowledgments:

Thanks to Ahmed Saleh for supporting me with the ChatGPT Apps concept, Abbey from freeCodeCamp for her patience during the editorial process, and the Supabase and OpenAI teams for their awesome work and documentation!

References:

This blog would not have been written without the hard work of the OpenAI, Supabase, and DigitalOcean teams that they put into the following documentation:

How to Build an Agentic Terminal Workflow with GitHub Copilot CLI and MCP Servers

Caleb Mintoumba — Wed, 29 Apr 2026 14:14:42 +0000

Most developers live in their terminal. You run commands, debug pipelines, manage infrastructure, and navigate codebases, all from a shell prompt.

But despite how central the terminal is to developer workflows, AI assistance there has remained shallow: autocomplete a command here, explain an error there.

That changes when you combine GitHub Copilot CLI with MCP (Model Context Protocol) servers. Instead of an AI that reacts to isolated prompts, you get a terminal that understands your project context, queries live data sources, and chains tool calls autonomously – what the industry is starting to call an agentic workflow.

In this tutorial, you'll learn exactly how to wire these two systems together, step by step. By the end, your terminal will be able to do things like understand your Git history before suggesting a fix, query your running Docker containers before writing a compose patch, or pull live API schemas before generating a request.

Prerequisites
What is GitHub Copilot CLI?
What is the Model Context Protocol?
How MCP Servers Work in a Terminal Context
Step 1 – Install and Configure GitHub Copilot CLI
Step 2 – Set Up Your First MCP Server
Step 3 – Wire Copilot CLI to Your MCP Server
Step 4 – Build a Real Agentic Workflow
Step 5 – Extend with Multiple MCP Servers
Debugging Common Issues
Conclusion

Prerequisites

Before you start, make sure you have the following:

Node.js v18 or later (node --version)
npm v9 or later
A GitHub account with Copilot enabled. The free tier (available to all GitHub users) is sufficient to follow this tutorial. Pro, Business, and Enterprise plans unlock higher usage limits but aren't required.
GitHub CLI (gh) installed. We'll use it to authenticate.
Basic familiarity with the terminal and JSON configuration files
(Optional) Docker installed if you want to follow the Docker MCP example in Step 5

You don't need prior experience with MCP or agentic AI systems, as this guide builds that understanding from the ground up.

What is GitHub Copilot CLI?

GitHub Copilot CLI is the terminal-native interface to GitHub's Copilot AI. Unlike the IDE plugin (which assists with code completion), Copilot CLI is designed specifically for shell workflows. It exposes three main commands:

gh copilot suggest proposes a shell command based on a natural language description
gh copilot explain explains what a given command does
gh copilot alias generates shell aliases for Copilot subcommands

Here's a quick example of suggest in action:

gh copilot suggest "find all files modified in the last 24 hours and larger than 1MB"

Copilot will return something like:

find . -mtime -1 -size +1M

It will also ask if you want to copy it, run it directly, or revise the request. This interactive loop is already useful – but by itself, Copilot CLI has no awareness of your project context. It doesn't know your repo structure, your running services, or your deployment environment. That's where MCP comes in.

What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard introduced by Anthropic in late 2024. Its goal is straightforward: give AI models a standardized way to connect to external tools, data sources, and services.

Think of MCP as a universal adapter layer between an AI model and the real world. Without MCP, each AI integration is custom-built: one plugin for GitHub, another for Postgres, another for Slack, all with incompatible interfaces. MCP defines a single protocol that any tool can implement, and any compatible AI client can consume.

An MCP server exposes tools (functions the AI can call), resources (data the AI can read), and prompts (reusable instruction templates). The AI client in our case, a Copilot-powered terminal discovers these capabilities at runtime and uses them autonomously to complete a task.

A few notable MCP servers that are already production-ready:

MCP Server	What it exposes
@modelcontextprotocol/server-filesystem	Read/write access to local files
@modelcontextprotocol/server-git	Git log, diff, blame, branch operations
@modelcontextprotocol/server-github	GitHub Issues, PRs, repos via API
@modelcontextprotocol/server-postgres	Live query execution on a Postgres DB
@modelcontextprotocol/server-docker	Container inspection, logs, stats

The full registry lives at github.com/modelcontextprotocol/servers.

How MCP Servers Work in a Terminal Context

Before we get hands-on, it's worth understanding the communication model.

MCP servers run as local processes. They communicate with the AI client over stdio (standard input/output) or over an HTTP/SSE transport. The client sends JSON-RPC messages to the server, and the server responds with structured data.

Here's the simplified flow:

The key word here is grounded. Without MCP, Copilot responds based purely on its training data and your prompt. With MCP, it can call git log --oneline -20 before answering your question about recent regressions and its answer is based on your actual code history, not a generalized assumption.

Step 1 – Install and Configure GitHub Copilot CLI

If you haven't already, install the GitHub CLI:

# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Windows (via winget)
winget install --id GitHub.cli

Then authenticate:

gh auth login

Follow the interactive prompts. Select GitHub.com, then HTTPS, and authenticate via browser when prompted.

Now install the Copilot CLI extension:

gh extension install github/gh-copilot

Verify the installation:

gh copilot --version

You should see output like gh-copilot version 1.x.x.

Optional but recommended: set up shell aliases. This makes the workflow much faster. For bash or zsh:

# Add to your ~/.bashrc or ~/.zshrc
eval "$(gh copilot alias -- bash)"   # for bash
eval "$(gh copilot alias -- zsh)"    # for zsh

After reloading your shell (source ~/.bashrc), you can use ghcs as shorthand for gh copilot suggest and ghce for gh copilot explain.

Step 2 – Set Up Your First MCP Server

We'll start with server-git. It's the most immediately useful for a development workflow and has zero external dependencies.

Install it globally via npm:

npm install -g @modelcontextprotocol/server-git

Test that it runs:

mcp-server-git --version

This server exposes the following tools to any compatible MCP client:

git_log retrieve commit history with filters
git_diff diff between branches or commits
git_status current working tree status
git_show inspect a specific commit
git_blame annotate file lines with commit info
git_branch list or switch branches

Now create a configuration file. MCP clients look for a file called mcp.json to discover available servers. Create it in your project root or in a global config directory:

mkdir -p ~/.config/mcp
touch ~/.config/mcp/mcp.json

Add the following content:

{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--repository", "."],
      "transport": "stdio"
    }
  }
}

A few notes on this config:

command is the binary to run. Make sure it's on your $PATH.
args passes --repository . so the server scopes itself to the current working directory.
transport: "stdio" means communication happens over standard input/output the simplest and most stable option for local servers.

Step 3 – Wire Copilot CLI to Your MCP Server

This is where the two systems connect. GitHub Copilot CLI supports MCP via its --mcp-config flag (available from version 1.3+). You point it at your mcp.json, and Copilot will automatically initialize the declared servers before processing your prompt.

Here's the basic invocation:

gh copilot suggest --mcp-config ~/.config/mcp/mcp.json "why did the build break in the last commit?"

When you run this inside a Git repository, Copilot CLI will:

Start the mcp-server-git process
Call git_log to retrieve recent commits
Call git_diff on the most recent commit
Synthesize an answer based on the actual diff output

Try it yourself on a repo with a recent failing commit. The difference in response quality compared to a plain gh copilot suggest is immediately obvious.

Tip: avoid retyping the flag every time. Add a shell function to your .bashrc/.zshrc:

function aterm() {
  gh copilot suggest --mcp-config ~/.config/mcp/mcp.json "$@"
}

Now you just type:

aterm "what changed between main and feature/auth?"

And you're running a fully context-aware, MCP-powered query from a single short command. This function name aterm for agentic terminal is what we'll use throughout the rest of this tutorial.

Step 4 – Build a Real Agentic Workflow

Let's move beyond individual queries and build a workflow that chains multiple tool calls to complete a real developer task: diagnosing a regression.

Imagine you pushed a feature branch and your CI pipeline failed. You don't know exactly which change caused it. Here's how your agentic terminal handles it:

Query 1: understand what changed

aterm "summarize all commits on feature/auth that aren't on main yet"

Copilot calls git_log with branch filters, then returns a structured summary of commits unique to your branch. No copy-pasting SHAs manually.

Query 2: isolate the diff

aterm "show me everything that changed in the auth middleware between main and feature/auth"

This triggers git_diff scoped to the path containing your middleware. Copilot returns the diff with an explanation of what each change does.

Query 3: find the likely culprit

aterm "which of those changes could cause a JWT validation failure?"

At this point, Copilot has the diff in its context window from the previous tool calls. It reasons over the actual code changes not generic knowledge about JWT and pinpoints the likely issue.

Query 4: generate the fix

aterm "write the corrected version of that validation function"

Copilot generates a targeted fix based on the specific code it retrieved via MCP. You get a patch you can directly apply, not a generic code template.

This four-step sequence – understand, isolate, reason, fix – is a complete agentic loop. Each step is grounded in live repository data retrieved through MCP tools. The AI is not hallucinating context. Instead, it's reading your actual codebase.

Step 5 – Extend with Multiple MCP Servers

One MCP server is useful. Multiple MCP servers working together is where the workflow becomes genuinely powerful. Let's add two more: server-filesystem and server-docker.

Install the additional servers:

npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-docker

Update your mcp.json:

{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--repository", "."],
      "transport": "stdio"
    },
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--root", "."],
      "transport": "stdio"
    },
    "docker": {
      "command": "mcp-server-docker",
      "transport": "stdio"
    }
  }
}

With all three servers active, your terminal can now answer cross-domain questions:

aterm "my Express app container keeps restarting, check the logs and compare with what the healthcheck in my Dockerfile expects"

To answer this, Copilot will:

Call docker_logs (server-docker) to pull the container's recent stderr output
Call read_file (server-filesystem) to read your Dockerfile
Parse the HEALTHCHECK instruction
Cross-reference the log errors with the health endpoint path
Return a diagnosis explaining the mismatch and suggest the fix

This is an agentic workflow: the model autonomously decides which tools to call, in what order, and synthesizes the results into a coherent answer. You didn't tell it to read the Dockerfile. It inferred that was necessary based on your question.

A note on security: When running server-filesystem, always scope it to a specific directory using --root. Never point it at / or your home directory. Similarly, server-docker has access to your Docker socket run it only in trusted environments.

Debugging Common Issues

mcp-server-git: command not found

The npm global bin directory isn't on your $PATH. Fix:

export PATH="\(PATH:\)(npm bin -g)"
# or for newer npm versions:
export PATH="\(PATH:\)(npm prefix -g)/bin"

Add this line to your .bashrc/.zshrc to persist it.

Copilot CLI doesn't seem to be using MCP tools

Check your Copilot CLI version:

gh copilot --version

MCP support requires version 1.3 or later. Update with:

gh extension upgrade copilot

Also verify your mcp.json is valid JSON a trailing comma or missing bracket will silently prevent server initialization.

MCP server starts but returns no data

Run the server manually to check for errors:

mcp-server-git --repository .

If it exits immediately, check that you're running the command inside a valid Git repository. For server-docker, make sure the Docker daemon is running and your user has access to the Docker socket:

sudo usermod -aG docker $USER
# Then log out and back in

Responses are slow with multiple servers

Each MCP server is a separate subprocess. Spawning several at once adds startup latency, especially on slower machines. Two optimizations:

Only declare the servers you actually need for a given project in your mcp.json
Use project-specific config files instead of one global config:

# project A (backend)
aterm --mcp-config ./mcp-backend.json "..."

# project B (infra)
aterm --mcp-config ./mcp-infra.json "..."

Conclusion

You've just built an agentic terminal workflow from scratch. Here's a quick recap of what you did:

Installed and configured GitHub Copilot CLI with shell aliases for fast access
Set up MCP servers (server-git, server-filesystem, server-docker) and wired them through a mcp.json config
Created a shell function (aterm) that transparently passes your MCP config to every Copilot query
Built a multi-step agentic loop for diagnosing regressions using live Git data
Extended the setup with cross-domain tool orchestration across Git, filesystem, and Docker

The architecture you've built here is not a demo – it's a production-ready pattern. You can extend it with any MCP-compatible server: server-postgres for database-aware queries, server-github for issue and PR context, or custom MCP servers you write yourself for your internal APIs.

The terminal has always been the most powerful surface in a developer's environment. With Copilot CLI and MCP, it's finally becoming an intelligent one.

How to Build an MCP Server with Python, Docker, and Claude Code

Balajee Asish Brahmandam — Tue, 10 Mar 2026 21:41:44 +0000

Every MCP tutorial I've found so far has followed the same basic script: build a server, point Claude Desktop at it, screenshot the chat window, done.

This is fine if you want a demo. But it's not fine if you want something you can ship, defend in an interview, or hand to another developer without a README that starts with "first, install this Electron app."

So I built an MCP server in Python, containerized it with Docker, and wired it into Claude Code – all from the terminal, no GUI required.

This article walks through the full loop in one afternoon: what MCP actually is, why it matters now that OpenAI and Google have adopted it, the real security problems nobody puts in their tutorial (complete with CVEs), and every command you need to go from an empty directory to a working tool.

If you're between jobs and need a portfolio project that shows you understand how AI tooling actually works under the hood, this is the one.

What You Will Build

By the end of this tutorial, you will have:

A Python MCP server that exposes custom tools to any MCP-compatible AI client
A Docker container that packages the server for reproducible deployment
A working connection between that container and Claude Code in your terminal
An understanding of the security risks involved and how to mitigate the worst of them

The server we are building is a project scaffolder. You give it a project name and a language, and it generates a starter directory structure with the right files. It's simple enough to build in an afternoon, but useful enough to actually put on your résumé.

Prerequisites

You will need the following installed on your machine:

Python 3.10+ (check with python3 --version)
Docker (check with docker --version)
Claude Code with an active Claude Pro, Max, or API plan (check with claude --version)
Node.js 20+ (required by Claude Code – check with node --version)
A terminal you are comfortable in

If you don't have Claude Code installed yet, follow the official installation instructions. The npm installation method is deprecated, so make sure you use the native binary installer instead.

What is MCP (and Why Should You Care)?

The Model Context Protocol (MCP) is an open standard that lets AI models connect to external tools and data sources. Anthropic released it in November 2024, and within a year it became the default way to extend what an LLM can do. OpenAI adopted it in March 2025. Google DeepMind followed in April. The protocol now has over 97 million monthly SDK downloads and more than 10,000 active servers.

The easiest way to think about MCP is as a USB-C port for AI. Before MCP, every AI provider had its own way of calling tools. OpenAI had function calling. Google had their own format. If you wanted your tool to work with multiple models, you had to implement it multiple times. MCP gives you one interface that works everywhere.

Here is how the pieces fit together:

An MCP server exposes tools, resources, and prompts. It is your code.
An MCP client (like Claude Code, Claude Desktop, or Cursor) discovers those tools and calls them on behalf of the LLM.
The transport is how they communicate. For local servers, that's usually stdio (standard input/output). For remote servers, it's HTTP.

When you type a message in Claude Code and it decides to use one of your tools, here is what happens: Claude Code sends a JSON-RPC 2.0 message to your server over stdin, your server executes the tool and writes the result to stdout, and Claude Code reads it back. The LLM never talks to your server directly. The client is always in the middle.

If you want the deeper architecture breakdown, freeCodeCamp already has a solid explainer on how MCP works under the hood. Here, I will focus on building.

Why Claude Code Instead of Claude Desktop?

Most MCP tutorials use Claude Desktop as the client. That works, but Claude Code has a few advantages for developers:

It lives in your terminal. No GUI to configure. No JSON files to hand-edit in hidden config directories. You add an MCP server with one command and you are done.
It's already where you code. If you're writing the server, testing it, and connecting it, doing all of that in the same terminal session cuts the context switching.
It works on headless machines. If you're SSHing into a dev box or running in CI, Claude Desktop isn't an option. Claude Code is.
It's also an MCP server itself. Claude Code can expose its own tools (file reading, writing, shell commands) to other MCP clients via claude mcp serve. That's a neat trick we won't use today, but it's worth knowing about.

The relevant commands:

# Add an MCP server
claude mcp add  -- 

# List configured servers
claude mcp list

# Remove a server
claude mcp remove 

# Check MCP status inside Claude Code
/mcp

Step 1: Build the MCP Server

We're using FastMCP, a Python framework that handles all the protocol plumbing so you can focus on your tools. Create a new project directory and set it up:

mkdir mcp-scaffolder && cd mcp-scaffolder
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]>=1.25,<2"

Why pin the version? The MCP Python SDK v2.0 is in development and will change the transport layer significantly. Pinning to >=1.25,<2 keeps your server working until you're ready to migrate.

Now create server.py:

# server.py
from mcp.server.fastmcp import FastMCP
import os
import json

mcp = FastMCP("project-scaffolder")

# Templates for different languages
TEMPLATES = {
    "python": {
        "files": {
            "main.py": '"""Entry point."""\n\n\ndef main():\n    print("Hello, world!")\n\n\nif __name__ == "__main__":\n    main()\n',
            "requirements.txt": "",
            "README.md": "# {name}\n\nA Python project.\n\n## Setup\n\n```bash\npip install -r requirements.txt\npython main.py\n```\n",
            ".gitignore": "__pycache__/\n*.pyc\n.venv/\n",
        },
        "dirs": ["tests"],
    },
    "node": {
        "files": {
            "index.js": 'console.log("Hello, world!");\n',
            "package.json": '{{\n  "name": "{name}",\n  "version": "1.0.0",\n  "main": "index.js"\n}}\n',
            "README.md": "# {name}\n\nA Node.js project.\n\n## Setup\n\n```bash\nnpm install\nnode index.js\n```\n",
            ".gitignore": "node_modules/\n",
        },
        "dirs": [],
    },
    "go": {
        "files": {
            "main.go": 'package main\n\nimport "fmt"\n\nfunc main() {{\n\tfmt.Println("Hello, world!")\n}}\n',
            "go.mod": "module {name}\n\ngo 1.21\n",
            "README.md": "# {name}\n\nA Go project.\n\n## Setup\n\n```bash\ngo run main.go\n```\n",
            ".gitignore": "bin/\n",
        },
        "dirs": ["cmd", "internal"],
    },
}


@mcp.tool()
def scaffold_project(name: str, language: str) -> str:
    """Create a new project directory structure.

    Args:
        name: The project name (used as the directory name)
        language: The programming language - one of: python, node, go
    """
    language = language.lower().strip()

    if language not in TEMPLATES:
        return json.dumps({
            "error": f"Unsupported language: {language}",
            "supported": list(TEMPLATES.keys()),
        })

    template = TEMPLATES[language]
    base_path = os.path.join(os.getcwd(), name)

    if os.path.exists(base_path):
        return json.dumps({
            "error": f"Directory already exists: {name}",
        })

    # Create the project directory
    os.makedirs(base_path, exist_ok=True)

    # Create subdirectories
    for dir_name in template["dirs"]:
        os.makedirs(os.path.join(base_path, dir_name), exist_ok=True)

    # Create files
    created_files = []
    for filename, content in template["files"].items():
        filepath = os.path.join(base_path, filename)
        formatted_content = content.replace("{name}", name)
        with open(filepath, "w") as f:
            f.write(formatted_content)
        created_files.append(filename)

    return json.dumps({
        "status": "created",
        "path": base_path,
        "language": language,
        "files": created_files,
        "directories": template["dirs"],
    })


@mcp.tool()
def list_templates() -> str:
    """List all available project templates and their contents."""
    result = {}
    for lang, template in TEMPLATES.items():
        result[lang] = {
            "files": list(template["files"].keys()),
            "directories": template["dirs"],
        }
    return json.dumps(result, indent=2)


if __name__ == "__main__":
    mcp.run(transport="stdio")

A few things to notice about this code:

Tools return strings. MCP tools communicate through text. I'm returning JSON strings so the LLM can parse the results reliably. You could return plain text, but structured data gives the model more to work with.

The @mcp.tool() decorator does the heavy lifting. FastMCP reads your function signature and docstring to generate the JSON schema that tells the LLM what this tool does, what arguments it takes, and what types they are. Good docstrings aren't optional here – they're how the LLM decides whether to call your tool.

transport="stdio" is the key line. This tells FastMCP to communicate over standard input/output, which is what Claude Code expects for local servers.

Step 2: Test It Locally

Before we Dockerize anything, make sure the server actually works:

# Quick smoke test - the server should start without errors
python server.py

You should see... nothing. That is correct. An MCP server over stdio just sits there waiting for JSON-RPC messages on stdin. Press Ctrl+C to stop it.

For a proper test, use the MCP Inspector (Anthropic's debugging tool):

# Install and run the inspector
npx @modelcontextprotocol/inspector python server.py

This opens a web interface where you can see your tools, call them manually, and inspect the JSON-RPC messages going back and forth. Verify that both scaffold_project and list_templates show up and return sensible results.

Here's a debugging tip that will save you time: If your MCP server logs anything to stdout, it will corrupt the JSON-RPC stream and the client will disconnect. Use stderr for all logging: print("debug info", file=sys.stderr). This is the single most common source of "my server connects but then immediately fails" bugs. The New Stack called stdio transport "incredibly fragile" for exactly this reason.

Step 3: Dockerize It

Create a Dockerfile in your project root:

FROM python:3.12-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy server code
COPY server.py .

# MCP servers over stdio need unbuffered output
ENV PYTHONUNBUFFERED=1

# The server reads from stdin and writes to stdout
CMD ["python", "server.py"]

Create requirements.txt:

mcp[cli]>=1.25,<2

Build and verify:

docker build -t mcp-scaffolder .

# Quick test - should start without errors
docker run -i mcp-scaffolder

Again, you'll see nothing because the server is waiting for input. Ctrl+C to stop.

Two things matter in this Dockerfile:

PYTHONUNBUFFERED=1 is critical. Without it, Python buffers stdout, and the MCP client may hang waiting for responses that are sitting in a buffer. This is one of those bugs that works fine in local testing and breaks in Docker.
docker run -i (interactive mode) is required. The -i flag keeps stdin open so the MCP client can send messages to the container. Without it, the server gets an immediate EOF and exits.

Step 4: Wire It Into Claude Code

Now connect your Docker container to Claude Code:

claude mcp add scaffolder -- docker run -i --rm mcp-scaffolder

That's the whole command. Let me break it down:

claude mcp add registers a new MCP server
scaffolder is the name you will reference it by
Everything after -- is the command Claude Code runs to start the server
docker run -i --rm mcp-scaffolder starts the container with interactive stdin and removes it when done

Verify that it registered:

claude mcp list

You should see scaffolder in the output with a stdio transport type.

Now launch Claude Code and check the connection:

claude

Once inside Claude Code, type /mcp to see the status of your MCP servers. You should see scaffolder listed as connected with two tools available.

Step 5: Use It

Still inside Claude Code, try it out:

Create a new Python project called "weather-api"

Claude Code should discover your scaffold_project tool, call it with name="weather-api" and language="python", and report back what it created. Check your filesystem and you should see the full project structure.

Try a few more:

What project templates are available?

Scaffold a Go project called "url-shortener"

If Claude Code doesn't pick up your tools, run /mcp to check the connection status. If it shows as disconnected, the most common causes are that the Docker image failed to build, stdout is being polluted (check for stray print statements), or the Docker daemon is not running.

Security: What the Other Tutorials Leave Out

This is the section most MCP tutorials skip. They should not. MCP has had real security incidents, not theoretical ones, and understanding them makes you a better developer.

The Prompt Injection Problem

MCP servers execute code on your machine based on what an LLM decides to do. If an attacker can influence what the LLM sees, they can influence what your server does. This is called prompt injection, and it is the number one unsolved security problem in the MCP ecosystem.

In May 2025, researchers at Invariant Labs demonstrated this against the official GitHub MCP server. They created a malicious GitHub issue that, when read by an AI agent, hijacked the agent into leaking private repository data (including salary information) into a public pull request. The root cause was an overly broad Personal Access Token combined with untrusted content landing in the LLM's context window.

This was not a contrived lab demo. It used the official GitHub MCP server, the kind of thing people install from the MCP server directory without a second thought.

Real CVEs, Not Theory

The ecosystem has accumulated real vulnerability reports:

CVE-2025-6514: A critical command-injection bug in mcp-remote, a popular OAuth proxy that 437,000+ environments used. An attacker could execute arbitrary OS commands through crafted OAuth redirect URIs.
CVE-2025-6515: Session hijacking in oatpp-mcp through predictable session IDs, letting attackers inject prompts into other users' sessions.
MCP Inspector RCE: Anthropic's own debugging tool allowed unauthenticated remote code execution. Inspecting a malicious server meant giving the attacker a shell on your machine.

An Equixly security assessment found command injection in 43% of tested MCP server implementations. Nearly a third were vulnerable to server-side request forgery.

What You Should Actually Do

For the server we built today, here is what matters:

Limit file system access

Our Docker container doesn't mount your home directory. That's intentional. If you need the server to write files to your host, mount only the specific directory you need: docker run -i --rm -v $(pwd)/projects:/app/projects mcp-scaffolder. Never mount / or ~.

Validate all inputs

Our scaffold_project tool checks that the language is in a known list and that the directory does not already exist. But think about what happens if someone passes name="../../etc/passwd" as the project name. Path traversal is the kind of thing you need to catch. Add this to the tool:

# Add this validation at the top of scaffold_project
if ".." in name or "/" in name or "\\" in name:
    return json.dumps({"error": "Invalid project name"})

Use least-privilege tokens

If your MCP server connects to an API, give it the minimum permissions it needs. The GitHub MCP incident happened because the PAT had access to every private repo. A read-only token scoped to one repo would have contained the blast radius.

Do not install MCP servers from untrusted sources

A malicious npm package posing as a "Postmark MCP Server" was caught silently BCC'ing all emails to an attacker's address. Treat MCP server packages with the same caution you would give any code that runs on your machine with your permissions.

What to Do Next

You have a working MCP server in a Docker container, connected to Claude Code. Here is how to make it portfolio-ready:

Add more tools: The scaffolder is a starting point. Add a tool that reads a project's dependency file and lists outdated packages. Add one that generates a Dockerfile for an existing project. Each tool is a function with a decorator – the pattern is the same every time.
Add tests: Write pytest tests that call your tool functions directly and verify the output. MCP tools are just Python functions. Test them like Python functions.
Push the Docker image: Tag it and push to Docker Hub or GitHub Container Registry. Then your claude mcp add command becomes claude mcp add scaffolder -- docker run -i --rm yourusername/mcp-scaffolder:latest and anyone can use it.
Write a README that explains the security model: What permissions does your server need? What file system access? What happens if inputs are malicious? Answering these questions in your README signals that you think about security, which is exactly what hiring managers are looking for right now.

Wrapping Up

We built a Python MCP server with FastMCP, containerized it with Docker, and connected it to Claude Code. The whole thing fits in about 100 lines of Python, a six-line Dockerfile, and one claude mcp add command.

The MCP ecosystem is real and growing fast. The protocol has the backing of Anthropic, OpenAI, and Google. It's now governed by the Linux Foundation. But it's also young, and the security story is still being written. Build with it, but build with your eyes open.

If you want to go deeper, here are the resources I found most useful:

MCP specification: the actual protocol docs
Claude Code MCP documentation: how Claude Code implements MCP
FastMCP GitHub: the Python framework we used
AuthZed's timeline of MCP security incidents: required reading if you are building MCP servers for production
Simon Willison on MCP prompt injection: the clearest explanation of why this is hard to solve

The complete source code for this tutorial is on GitHub.

How to Build MCP Servers for Your Internal Data

Mayur Vekariya — Wed, 04 Mar 2026 15:04:09 +0000

The Model Context Protocol (MCP) is changing how AI applications connect to external tools and data. While some tutorials stop at "connect to GitHub" or "read a file," the real power of MCP is unlocking your internal data—databases, internal APIs, knowledge bases, and proprietary systems—for AI assistants in a structured, secure way.

In this guide, I'll walk you through building production-grade MCP servers that expose your organization's internal data to AI models. We'll go beyond simple examples and cover authentication, multi-tenancy, streaming, and deployment patterns you'll actually need.

Prerequisites
What is MCP and Why Does It Matter for Internal Data?
Architecture Overview
Setting Up the Project
Building the MCP Server
Adding Authentication
- Bearer Token Authentication
- OAuth 2.0 for MCP
Scoping Data Access Per User
Connecting to Internal APIs
Building a RAG Tool for Internal Documents
Production Deployment
Connecting Your MCP Server to AI Clients
- Claude Desktop
- Custom Application (using the MCP Client SDK)
Common Pitfalls
Wrapping Up

Prerequisites

This is an advanced guide. You should be comfortable with:

TypeScript / Node.js
REST APIs and server-side development
Basic understanding of LLMs and tool calling
Familiarity with protocols like JSON-RPC

What is MCP, and Why Does It Matter for Internal Data?

MCP is an open protocol (created by Anthropic) that standardizes how AI assistants discover and invoke external tools. Think of it as a USB-C port for AI — one standard interface that lets any AI model connect to any data source.

Before MCP, connecting an AI assistant to your internal database meant:

Writing custom tool definitions for each LLM provider
Hardcoding data access logic into your AI application
Rebuilding everything when you switched models or added new data sources

MCP separates the data layer from the AI layer. Your MCP server exposes tools and resources. Any MCP-compatible client—Claude, ChatGPT, your custom app—can use them without modification.

For internal data, this is significant because:

Your CRM, ERP, ticketing system, and wiki all become AI-accessible through one protocol
Access control stays in your MCP server, not scattered across AI application code
New AI models or clients automatically get access without rewiring integrations
Tool definitions live close to the data, making them easier to maintain and version

Architecture Overview

Here's what we're building:

The MCP server sits between your AI client and your internal systems. It handles:

Tool discovery: Tells the AI what operations are available
Parameter validation: Ensures the AI sends correct inputs
Data access: Queries your internal systems
Response formatting: Returns structured data the AI can reason about
Authentication: Verifies who's making the request

Setting Up the Project

Let's build an MCP server that exposes an internal employee directory and project management system.

mkdir internal-data-mcp && cd internal-data-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod express pg
npm install -D typescript @types/node @types/express @types/pg tsx

These commands scaffold the project. npm install pulls in the runtime dependencies: the official MCP SDK, Zod for schema validation, Express for the HTTP server, and pg for PostgreSQL. The -D flag installs TypeScript and its type definitions as dev-only dependencies — they're needed to compile the code but don't ship to production. tsx lets you run TypeScript directly during development without a separate compile step.

Now, create your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}

This TypeScript config targets ES2022, which supports modern JavaScript features like top-level await. "module": "Node16" and "moduleResolution": "Node16" are required when using the MCP SDK's .js import extensions. "strict": true enables all of TypeScript's strictness checks, which helps catch bugs in tool handlers before they reach production. The outDir/rootDir pair tells the compiler to take source files from src/ and emit compiled JavaScript into dist/.

Building the MCP Server

Step 1: Server Skeleton

Create src/server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer(
  { name: "internal-data", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

The McpServer class from the official SDK handles the JSON-RPC protocol, transport negotiation, and lifecycle management. We declare support for both tools (actions the AI can take) and resources (data the AI can read).

Step 2: Connecting to Internal Data

Let's say you have a PostgreSQL database with employee and project data. Create a data access layer:

// src/db.ts
import pg from "pg";

const pool = new pg.Pool({
  connectionString: process.env.INTERNAL_DB_URL,
  max: 10,
  idleTimeoutMillis: 30000,
});

export interface Employee {
  id: string;
  name: string;
  email: string;
  department: string;
  role: string;
  manager_id: string | null;
  start_date: string;
}

export interface Project {
  id: string;
  name: string;
  status: "active" | "completed" | "on_hold";
  lead_id: string;
  department: string;
  deadline: string | null;
}

export async function searchEmployees(
  query: string,
  department?: string
): Promise {
  const conditions = ["(name ILIKE \(1 OR email ILIKE \)1 OR role ILIKE $1)"];
  const params: string[] = [`%${query}%`];

  if (department) {
    conditions.push(`department = $${params.length + 1}`);
    params.push(department);
  }

  const result = await pool.query(
    `SELECT id, name, email, department, role, manager_id, start_date
     FROM employees
     WHERE ${conditions.join(" AND ")}
     ORDER BY name
     LIMIT 25`,
    params
  );

  return result.rows;
}

export async function getProjectsByStatus(
  status: string
): Promise {
  const result = await pool.query(
    `SELECT id, name, status, lead_id, department, deadline
     FROM projects
     WHERE status = $1
     ORDER BY deadline ASC NULLS LAST`,
    [status]
  );

  return result.rows;
}

export async function getProjectMembers(
  projectId: string
): Promise {
  const result = await pool.query(
    `SELECT e.id, e.name, e.email, e.department, e.role,
            e.manager_id, e.start_date
     FROM employees e
     JOIN project_members pm ON pm.employee_id = e.id
     WHERE pm.project_id = $1
     ORDER BY e.name`,
    [projectId]
  );

  return result.rows;
}

Notice this is plain SQL with parameterized queries. Your MCP server's data access layer should use whatever your team already uses — Prisma, Drizzle, Knex, raw SQL. MCP doesn't dictate your data access patterns.

Step 3: Defining Tools

Now expose this data through MCP tools. This is where the design matters most. Good tool definitions directly impact how well the AI uses your data.

// src/tools.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import {
  searchEmployees,
  getProjectsByStatus,
  getProjectMembers,
} from "./db.js";

export function registerTools(server: McpServer) {
  // Tool 1: Search the employee directory
  server.tool(
    "search_employees",
    `Search the internal employee directory by name, email, or role.
     Returns matching employees with their department and reporting structure.
     Use this when the user asks about people, teams, or org structure.`,
    {
      query: z
        .string()
        .describe("Search term: employee name, email, or role title"),
      department: z
        .string()
        .optional()
        .describe(
          "Filter by department name (e.g., 'Engineering', 'Marketing')"
        ),
    },
    async ({ query, department }) => {
      const employees = await searchEmployees(query, department);

      if (employees.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No employees found matching "\({query}"\){department ? ` in ${department}` : ""}.`,
            },
          ],
        };
      }

      const formatted = employees
        .map(
          (e) =>
            `- **\({e.name}** (\){e.email})\n  Role: \({e.role} | Dept: \){e.department} | Since: ${e.start_date}`
        )
        .join("\n");

      return {
        content: [
          {
            type: "text",
            text: `Found \({employees.length} employee(s):\n\n\){formatted}`,
          },
        ],
      };
    }
  );

  // Tool 2: List projects by status
  server.tool(
    "list_projects",
    `List internal projects filtered by status.
     Returns project name, lead, department, and deadline.
     Use this when the user asks about ongoing work, project status, or deadlines.`,
    {
      status: z
        .enum(["active", "completed", "on_hold"])
        .describe("Project status to filter by"),
    },
    async ({ status }) => {
      const projects = await getProjectsByStatus(status);

      if (projects.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No ${status} projects found.`,
            },
          ],
        };
      }

      const formatted = projects
        .map(
          (p) =>
            `- **\({p.name}** [\){p.status}]\n  Lead: \({p.lead_id} | Dept: \){p.department} | Deadline: ${p.deadline ?? "None"}`
        )
        .join("\n");

      return {
        content: [
          {
            type: "text",
            text: `\({projects.length} \){status} project(s):\n\n${formatted}`,
          },
        ],
      };
    }
  );

  // Tool 3: Get team members for a project
  server.tool(
    "get_project_team",
    `Get all team members assigned to a specific project.
     Returns employee details for each member.
     Use this when the user asks who is working on a project.`,
    {
      project_id: z
        .string()
        .uuid()
        .describe("The UUID of the project to look up"),
    },
    async ({ project_id }) => {
      const members = await getProjectMembers(project_id);

      if (members.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: "No team members found for this project.",
            },
          ],
        };
      }

      const formatted = members
        .map((m) => `- \({m.name} (\){m.role}, ${m.department})`)
        .join("\n");

      return {
        content: [
          {
            type: "text",
            text: `Project team (\({members.length} members):\n\n\){formatted}`,
          },
        ],
      };
    }
  );
}

server.tool() registers each tool with four arguments: the tool name, a plain-English description the AI reads to decide when to call it, a Zod schema defining the parameters, and the async handler that runs when the tool is invoked. The handler receives validated, typed parameters — Zod rejects malformed inputs before your handler ever runs. Each handler returns a content array; the type: "text" block is the most common format and tells the AI client to treat the response as readable text. Returning an empty result (zero matches) is handled explicitly so the AI gets a useful message rather than an empty array it might misinterpret.

Tool Design Principles

Three things make the difference between tools an AI uses well and tools it struggles with:

1. Descriptive names and descriptions. The AI decides which tool to call based entirely on the description. Be specific about when to use the tool, not just what it does. Compare:

// Vague — the AI won't know when to pick this
"Search employees"

// Specific — the AI knows exactly when this tool is relevant
"Search the internal employee directory by name, email, or role.
 Use this when the user asks about people, teams, or org structure."

2. Typed parameters with descriptions. Use Zod's .describe() on every parameter. The AI needs to understand what each field expects:

// The AI has to guess what format "query" expects
{ query: z.string() }

// The AI knows exactly what to pass
{ query: z.string().describe("Search term: employee name, email, or role title") }

3. Structured return values. Return data in a format the AI can reason about. Use markdown tables or structured lists rather than raw JSON dumps. The AI processes structured text better than deeply nested objects.

Step 4: Exposing Resources

Resources are read-only data the AI can pull into its context. Unlike tools (which the AI invokes during reasoning), resources are typically loaded upfront to provide background knowledge.

// src/resources.ts
import {
  McpServer,
  ResourceTemplate,
} from "@modelcontextprotocol/sdk/server/mcp.js";

export function registerResources(server: McpServer) {
  // Static resource: org chart overview
  server.resource(
    "org-structure",
    "internal://org-structure",
    {
      description:
        "Overview of the organization structure including departments and leadership",
      mimeType: "text/markdown",
    },
    async (uri) => ({
      contents: [
        {
          uri: uri.href,
          mimeType: "text/markdown",
          text: await generateOrgOverview(),
        },
      ],
    })
  );

  // Dynamic resource template: department details
  server.resource(
    "department-info",
    new ResourceTemplate("internal://departments/{name}", {
      list: undefined,
    }),
    {
      description: "Detailed information about a specific department",
      mimeType: "text/markdown",
    },
    async (uri, variables) => ({
      contents: [
        {
          uri: uri.href,
          mimeType: "text/markdown",
          text: await getDepartmentDetails(
            variables.name as string
          ),
        },
      ],
    })
  );
}

server.resource() registers two kinds of resources here. The first uses a fixed URI (internal://org-structure) — this is a static resource the AI can request by name. The second uses a ResourceTemplate, which defines a URI pattern with a {name} placeholder; the AI can request internal://departments/Engineering and the variables.name parameter will be populated with "Engineering" at runtime. Both resources return a contents array with mimeType: "text/markdown" — this tells the client how to render the response. Resources differ from tools in that they're meant to be read as background context, not invoked as actions.

Resources are useful for data that provides context rather than answering a specific question — company policies, API documentation, database schemas, configuration references.

Step 5: Transport and Startup

MCP supports multiple transports. For internal data servers, you'll typically use one of two:

Streamable HTTP — the recommended transport for remote servers (replaces the older SSE transport):

// src/index.ts
import express from "express";
import { randomUUID } from "node:crypto";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { registerTools } from "./tools.js";
import { registerResources } from "./resources.js";

const app = express();
app.use(express.json());

const server = new McpServer(
  { name: "internal-data", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

registerTools(server);
registerResources(server);

// Store transports by session ID
const transports = new Map();

// Handle all MCP requests on a single endpoint
app.all("/mcp", async (req, res) => {
  // Check for existing session
  const sessionId = req.headers["mcp-session-id"] as string | undefined;

  if (sessionId && transports.has(sessionId)) {
    // Existing session — route to its transport
    const transport = transports.get(sessionId)!;
    await transport.handleRequest(req, res);
    return;
  }

  if (sessionId && !transports.has(sessionId)) {
    // Unknown session ID
    res.status(404).json({ error: "Session not found" });
    return;
  }

  // New session — create transport and connect
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: () => randomUUID(),
    onsessioninitialized: (id) => {
      transports.set(id, transport);
    },
  });

  transport.onclose = () => {
    if (transport.sessionId) {
      transports.delete(transport.sessionId);
    }
  };

  await server.connect(transport);
  await transport.handleRequest(req, res);
});

app.listen(3100, () => {
  console.log("MCP server running on http://localhost:3100/mcp");
});

This sets up a single /mcp endpoint that handles all MCP communication. When a new client connects (no mcp-session-id header), a StreamableHTTPServerTransport is created and stored in the transports Map keyed by a generated UUID. On subsequent requests, the session ID from the header is used to look up the existing transport and route the request to it — this is how the server maintains stateful sessions with multiple clients simultaneously. transport.onclose cleans up the Map entry when a session ends, preventing memory leaks. The StdioServerTransport alternative (shown below) skips all of this: it reads from stdin and writes to stdout, which is how Claude Desktop spawns local servers as child processes.

Stdio — for local development or when the MCP client spawns the server as a child process:

// src/stdio.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { registerTools } from "./tools.js";
import { registerResources } from "./resources.js";

const server = new McpServer(
  { name: "internal-data", version: "1.0.0" },
  { capabilities: { tools: {}, resources: {} } }
);

registerTools(server);
registerResources(server);

const transport = new StdioServerTransport();
await server.connect(transport);

For internal data in a production setting, HTTP/SSE is almost always what you want. Stdio is convenient for development and when the client and server run on the same machine.

Adding Authentication

Internal data servers need authentication. You don't want every AI client on the network querying your employee database unauthenticated.

Bearer Token Authentication

The simplest approach is to validate a token on every request:

// src/auth-middleware.ts
import { Request, Response, NextFunction } from "express";

interface AuthenticatedRequest extends Request {
  userId?: string;
  orgId?: string;
}

export function authMiddleware(
  req: AuthenticatedRequest,
  res: Response,
  next: NextFunction
) {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith("Bearer ")) {
    return res.status(401).json({ error: "Missing authorization header" });
  }

  const token = authHeader.slice(7);

  try {
    // Validate against your internal auth system
    const claims = validateInternalToken(token);
    req.userId = claims.sub;
    req.orgId = claims.org;
    next();
  } catch {
    return res.status(403).json({ error: "Invalid token" });
  }
}

function validateInternalToken(token: string) {
  // Replace with your actual token validation:
  // - JWT verification against your auth service
  // - API key lookup in your database
  // - Session token validation against Redis
  // This is a placeholder
  return { sub: "user-123", org: "org-456" };
}

The middleware checks every request for an Authorization: Bearer header before it reaches the MCP handler. validateInternalToken is a placeholder — replace it with your real validation logic: JWT verification using a library like jsonwebtoken, an API key lookup in your database, or a session token check against Redis. The validated claims are attached to the request object (req.userId, req.orgId) so downstream tool handlers can use them for access scoping. The app.use("/mcp", authMiddleware) line ensures no request reaches the MCP endpoint without passing this check first.

Add it to your Express app:

app.use("/mcp", authMiddleware);

OAuth 2.0 for MCP

For clients that support MCP's built-in OAuth flow (like Claude Desktop), you can implement the full OAuth handshake. The MCP SDK provides the OAuthServerProvider interface with these required methods:

import type { OAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/provider.js";
import type {
  AuthorizationParams,
  OAuthClientInformationFull,
  OAuthRegisteredClientsStore,
  OAuthTokens,
  AuthInfo,
} from "@modelcontextprotocol/sdk/server/auth/types.js";

class InternalOAuthProvider implements OAuthServerProvider {
  // Store for registered OAuth clients
  get clientsStore(): OAuthRegisteredClientsStore {
    return this._clientsStore;
  }

  private _clientsStore: OAuthRegisteredClientsStore = {
    async getClient(clientId: string) {
      // Look up the registered client in your database
      return db.getOAuthClient(clientId);
    },
    async registerClient(clientMetadata) {
      // Register a new dynamic client
      return db.createOAuthClient(clientMetadata);
    },
  };

  // Redirect the user to your internal SSO for authorization
  async authorize(
    client: OAuthClientInformationFull,
    params: AuthorizationParams,
    res: Response
  ): Promise {
    const authUrl = new URL(
      "https://sso.internal.company.com/authorize"
    );
    authUrl.searchParams.set("client_id", client.client_id);
    authUrl.searchParams.set("redirect_uri", params.redirectUri);
    authUrl.searchParams.set("state", params.state ?? "");
    authUrl.searchParams.set(
      "code_challenge",
      params.codeChallenge
    );
    // The method writes to the response directly
    res.redirect(authUrl.toString());
  }

  // Return the PKCE challenge for a given authorization code
  async challengeForAuthorizationCode(
    _client: OAuthClientInformationFull,
    authorizationCode: string
  ): Promise {
    const session = await db.getSessionByCode(authorizationCode);
    return session.codeChallenge;
  }

  // Exchange authorization code for access + refresh tokens
  async exchangeAuthorizationCode(
    client: OAuthClientInformationFull,
    authorizationCode: string,
    _codeVerifier?: string,
    _redirectUri?: string
  ): Promise {
    const response = await fetch(
      "https://sso.internal.company.com/token",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: new URLSearchParams({
          grant_type: "authorization_code",
          code: authorizationCode,
          client_id: client.client_id,
        }),
      }
    );

    return response.json() as Promise;
  }

  // Refresh expired tokens
  async exchangeRefreshToken(
    client: OAuthClientInformationFull,
    refreshToken: string
  ): Promise {
    const response = await fetch(
      "https://sso.internal.company.com/token",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: new URLSearchParams({
          grant_type: "refresh_token",
          refresh_token: refreshToken,
          client_id: client.client_id,
        }),
      }
    );

    return response.json() as Promise;
  }

  // Validate an access token on every request
  async verifyAccessToken(token: string): Promise {
    const response = await fetch(
      "https://sso.internal.company.com/introspect",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/x-www-form-urlencoded",
        },
        body: new URLSearchParams({ token }),
      }
    );

    const data = await response.json();
    if (!data.active) throw new Error("Token inactive");

    return {
      token,
      clientId: data.client_id,
      scopes: data.scope?.split(" ") ?? [],
      expiresAt: data.exp,
    };
  }
}

InternalOAuthProvider implements the OAuthServerProvider interface, which the MCP SDK calls at each stage of the OAuth flow. clientsStore handles dynamic client registration — MCP clients like Claude Desktop register themselves the first time they connect. authorize() redirects the user to your internal SSO; it writes directly to the Express response. challengeForAuthorizationCode() returns the PKCE code challenge stored when the authorization session began — this is how the token exchange is verified without transmitting secrets. exchangeAuthorizationCode() and exchangeRefreshToken() make server-to-server calls to your SSO's token endpoint, keeping credentials out of the browser. verifyAccessToken() is called on every incoming MCP request using the token introspection endpoint to confirm the token is still active and extract the user's scopes.

Scoping Data Access Per User

This is the most important part of an internal data MCP server: the AI should only access data the requesting user is authorized to see.

Don't skip this. Without user-scoped access, you're building a data exfiltration tool with an AI wrapper.

// src/scoped-tools.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function registerScopedTools(
  server: McpServer,
  getUserContext: () => { userId: string; orgId: string; role: string }
) {
  server.tool(
    "search_employees",
    "Search the employee directory. Results are filtered based on your access level.",
    {
      query: z.string().describe("Name, email, or role to search for"),
    },
    async ({ query }) => {
      const ctx = getUserContext();

      // Enforce access boundaries
      let departmentFilter: string | undefined;

      if (ctx.role === "manager") {
        // Managers see their department only
        departmentFilter = await getUserDepartment(ctx.userId);
      } else if (ctx.role === "employee") {
        // Regular employees see limited fields
        departmentFilter = await getUserDepartment(ctx.userId);
      }
      // Admins and HR see everything — no filter

      const employees = await searchEmployees(query, departmentFilter);

      // Redact sensitive fields based on role
      const results = employees.map((e) => ({
        name: e.name,
        email: e.email,
        department: e.department,
        role: e.role,
        // Only HR and admins see start date and manager info
        ...(["admin", "hr"].includes(ctx.role)
          ? { start_date: e.start_date, manager_id: e.manager_id }
          : {}),
      }));

      return {
        content: [
          {
            type: "text",
            text: formatEmployeeList(results),
          },
        ],
      };
    }
  );
}

The pattern here:

Extract user context from the authenticated session
Filter queries at the database level (not after fetching everything)
Redact fields the user shouldn't see
Log access for audit trails

Connecting to Internal APIs

Not all internal data lives in databases. You often need to wrap existing internal APIs:

server.tool(
  "get_ticket_details",
  `Look up a support ticket from the internal ticketing system.
   Returns ticket status, assignee, priority, and recent updates.`,
  {
    ticket_id: z
      .string()
      .regex(/^TK-\d+$/)
      .describe("Ticket ID in format TK-12345"),
  },
  async ({ ticket_id }) => {
    const ctx = getUserContext();

    const response = await fetch(
      `\({process.env.TICKETING_API_URL}/api/v2/tickets/\){ticket_id}`,
      {
        headers: {
          Authorization: `Bearer ${process.env.TICKETING_SERVICE_TOKEN}`,
          "X-On-Behalf-Of": ctx.userId,
        },
      }
    );

    if (response.status === 404) {
      return {
        content: [
          { type: "text", text: `Ticket ${ticket_id} not found.` },
        ],
      };
    }

    if (response.status === 403) {
      return {
        content: [
          {
            type: "text",
            text: `You don't have access to ticket ${ticket_id}.`,
          },
        ],
      };
    }

    const ticket = await response.json();

    return {
      content: [
        {
          type: "text",
          text: [
            `**\({ticket.id}: \){ticket.title}**`,
            `Status: \({ticket.status} | Priority: \){ticket.priority}`,
            `Assignee: ${ticket.assignee?.name ?? "Unassigned"}`,
            `Created: ${ticket.created_at}`,
            "",
            `**Latest Update:**`,
            ticket.updates?.[0]?.body ?? "No updates yet.",
          ].join("\n"),
        },
      ],
    };
  }
);

Key points when wrapping internal APIs:

Use service tokens for server-to-server auth, but pass user identity via headers like X-On-Behalf-Of
Handle HTTP errors explicitly — return user-friendly messages, not raw error objects
Validate input formats — the regex on ticket_id prevents injection and guides the AI on expected format
Don't leak internal implementation details in error messages

Building a RAG Tool for Internal Documents

One of the highest-value use cases: letting the AI search your internal knowledge base. Here's a tool that performs vector search against an internal document store:

server.tool(
  "search_internal_docs",
  `Search the internal knowledge base for relevant documents.
   Covers engineering docs, runbooks, architecture decisions, and policies.
   Use this when the user asks about internal processes, systems, or decisions.`,
  {
    query: z
      .string()
      .describe("Natural language search query"),
    category: z
      .enum(["engineering", "policy", "runbook", "architecture", "all"])
      .default("all")
      .describe("Document category to search within"),
    limit: z
      .number()
      .min(1)
      .max(10)
      .default(5)
      .describe("Maximum number of results"),
  },
  async ({ query, category, limit }) => {
    // Generate embedding for the search query
    const embedding = await generateEmbedding(query);

    // Vector similarity search against your document store
    const results = await pool.query(
      `SELECT
         d.id,
         d.title,
         d.category,
         d.content_chunk,
         d.source_url,
         d.updated_at,
         1 - (d.embedding <=> $1::vector) AS similarity
       FROM document_chunks d
       WHERE (\(2 = 'all' OR d.category = \)2)
         AND 1 - (d.embedding <=> $1::vector) > 0.7
       ORDER BY d.embedding <=> $1::vector
       LIMIT $3`,
      [JSON.stringify(embedding), category, limit]
    );

    if (results.rows.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No relevant documents found for "${query}".`,
          },
        ],
      };
    }

    const formatted = results.rows
      .map(
        (doc, i) =>
          `### \({i + 1}. \){doc.title}\n` +
          `Category: \({doc.category} | Updated: \){doc.updated_at} | Relevance: ${(doc.similarity * 100).toFixed(0)}%\n\n` +
          `${doc.content_chunk}\n\n` +
          `Source: ${doc.source_url}`
      )
      .join("\n\n---\n\n");

    return {
      content: [
        {
          type: "text",
          text: `Found \({results.rows.length} relevant document(s):\n\n\){formatted}`,
        },
      ],
    };
  }
);

This tool combines two operations: embedding generation and vector similarity search. generateEmbedding(query) calls an embedding model (such as OpenAI's text-embedding-3-small or a self-hosted model) to convert the user's query into a numeric vector. The SQL query then uses pgvector's <=> operator to compute cosine distance between the query vector and stored document chunk embeddings — lower distance means higher similarity. The 1 - (embedding <=> $1) > 0.7 condition filters out results below 70% similarity, so the AI doesn't receive loosely related noise. Results are ordered by ascending distance (most similar first) and capped by the limit parameter. The formatted output includes a relevance percentage so the AI can communicate confidence levels to the user.

Production Deployment

Dockerizing the MCP Server

FROM node:22-slim AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-slim AS runtime

WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

ENV NODE_ENV=production
EXPOSE 3100

HEALTHCHECK --interval=30s --timeout=5s \
  CMD curl -f http://localhost:3100/health || exit 1

CMD ["node", "dist/index.js"]

The Dockerfile uses a two-stage build. The builder stage installs all dependencies (including devDependencies) and compiles TypeScript to JavaScript in dist/. The runtime stage starts fresh from a clean Node image and copies only the compiled output and node_modules — devDependencies like TypeScript are excluded, keeping the final image small. The HEALTHCHECK instruction tells Docker (and orchestrators like Kubernetes) to poll /health every 30 seconds; if the endpoint fails, the container is marked unhealthy and can be automatically restarted or removed from the load balancer rotation.

Health Checks and Monitoring

Add a health endpoint that verifies your dependencies:

app.get("/health", async (_req, res) => {
  const checks = {
    database: false,
    ticketingApi: false,
  };

  try {
    await pool.query("SELECT 1");
    checks.database = true;
  } catch {}

  try {
    const resp = await fetch(
      `${process.env.TICKETING_API_URL}/health`
    );
    checks.ticketingApi = resp.ok;
  } catch {}

  const healthy = Object.values(checks).every(Boolean);
  res.status(healthy ? 200 : 503).json({
    status: healthy ? "healthy" : "degraded",
    checks,
    uptime: process.uptime(),
  });
});

The /health endpoint runs two dependency checks in parallel: a lightweight SELECT 1 query to confirm the database connection is live, and an HTTP ping to the ticketing API. Both results are collected into a checks object. If any check fails, the endpoint returns HTTP 503 (Service Unavailable) — this is the signal load balancers and container orchestrators use to stop routing traffic to an unhealthy instance. process.uptime() is included as a diagnostic field so you can quickly tell whether a degraded instance just started or has been running for hours.

Logging and Audit Trail

Every tool invocation against internal data should be logged:

function createAuditLogger() {
  return {
    logToolCall(params: {
      userId: string;
      tool: string;
      input: Record;
      resultSize: number;
      durationMs: number;
    }) {
      // Ship to your logging infrastructure
      // (Datadog, ELK, CloudWatch, etc.)
      console.log(
        JSON.stringify({
          event: "mcp_tool_call",
          timestamp: new Date().toISOString(),
          ...params,
        })
      );
    },
  };
}

createAuditLogger returns a logger object rather than a class instance, which makes it easy to swap the underlying transport (stdout, a logging SDK, etc.) without changing the call sites. The audited wrapper function is a higher-order function: it takes a tool handler and returns a new function with the same signature, but with timing and logging added around the original call. The try/catch ensures a log entry is written even when the handler throws — you want failed calls in your audit trail, not just successful ones. Shipping these logs to a centralized store (Datadog, CloudWatch, ELK) lets you answer questions like "what data did this user's AI session access last Tuesday?" — which is often required for compliance in organizations handling sensitive internal data.

Wrap your tool handlers to automatically log every call:

function audited>(
  handler: (params: T) => Promise,
  toolName: string,
  audit: ReturnType
) {
  return async (params: T): Promise => {
    const start = Date.now();
    const ctx = getUserContext();

    try {
      const result = await handler(params);
      audit.logToolCall({
        userId: ctx.userId,
        tool: toolName,
        input: params,
        resultSize: JSON.stringify(result).length,
        durationMs: Date.now() - start,
      });
      return result;
    } catch (error) {
      audit.logToolCall({
        userId: ctx.userId,
        tool: toolName,
        input: params,
        resultSize: 0,
        durationMs: Date.now() - start,
      });
      throw error;
    }
  };
}

Connecting Your MCP Server to AI Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "internal-data": {
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer your-internal-token"
      }
    }
  }
}

Custom Application (using the MCP Client SDK)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3100/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${userToken}`,
      },
    },
  }
);

const client = new Client(
  { name: "my-ai-app", version: "1.0.0" }
);

await client.connect(transport);

// Discover available tools
const { tools } = await client.listTools();
console.log("Available tools:", tools.map((t) => t.name));

// Call a tool
const result = await client.callTool({
  name: "search_employees",
  arguments: { query: "engineering manager" },
});

console.log(result.content);

StreamableHTTPClientTransport manages the HTTP connection to your MCP server, including attaching the Authorization header to every request. client.connect(transport) performs the MCP initialization handshake — the client announces its capabilities and the server responds with the list of available tools and resources. client.listTools() returns the full tool catalog, which you can use to dynamically build a UI or pass directly to an LLM's tool-calling API. client.callTool() sends a JSON-RPC request to invoke a specific tool by name and returns the content array from the handler — the same format the AI model receives. In a production application, you'd pass this content back to the model as a tool result in the conversation history.

Common Pitfalls

1. Returning too much data. LLMs have context limits. If your database query returns 500 rows, don't send them all. Paginate, summarize, or limit results. 25 items is a reasonable default.

2. Tool descriptions that are too generic. If you have search_employees and search_contractors, the AI needs to know the difference. Don't rely on the tool name alone — the description is what the model reads.

3. Missing error handling. When a database query fails, return a structured error message, not a stack trace. The AI needs to tell the user something useful, and raw errors leak implementation details.

4. No rate limiting. AI tool calls can happen in loops. If the model calls your tool 50 times in one conversation, you need circuit breakers:

const rateLimiter = new Map();

function checkRateLimit(userId: string, limit = 30, windowMs = 60000) {
  const now = Date.now();
  const calls = rateLimiter.get(userId) ?? [];
  const recent = calls.filter((t) => now - t < windowMs);

  if (recent.length >= limit) {
    throw new Error(
      `Rate limit exceeded. Max ${limit} calls per minute.`
    );
  }

  recent.push(now);
  rateLimiter.set(userId, recent);
}

5. Not testing with actual AI models. Your tools might look correct in unit tests but confuse the model. Test the full loop: AI model receives tool definitions, decides to call a tool, gets the result, and reasons about it. Adjust descriptions based on how the model actually behaves.

Wrapping Up

Building MCP servers for internal data is about three things:

Good tool design — clear descriptions, typed parameters, structured responses
Proper access control — authenticate users, scope data access, log everything
Production readiness — health checks, rate limiting, error handling, monitoring

The protocol itself is straightforward. The hard work is designing the right abstractions over your internal systems so the AI can use them effectively without leaking data or overwhelming the context window.

Start with one or two high-value tools (employee lookup, document search), test them with real users, and expand from there. The best internal MCP servers grow organically based on what people actually ask the AI.

The full source code from this guide is available on GitHub.

How to Use the Model Context Protocol (MCP) with Flutter and Dart

Atuoha Anthony — Fri, 24 Oct 2025 19:46:36 +0000

Software development is moving fast toward AI-assisted workflows and smarter tooling. Whether it’s your IDE completing code, an AI assistant analyzing your project, or automated testing pipelines, all these tools need a standardized way to communicate. That’s where the Model Context Protocol (MCP) comes in.

If you’ve been hearing about MCP and wondering what it means for you as a Dart or Flutter developer, this guide is for you. It explains what MCP is and how it connects with Dart through the official dart_mcp package. You’ll also learn how you can start building or integrating MCP-based tools yourself, so AI can actually understand and act on your Flutter/Dart project, not just answer questions about pasted code.

By the end of this guide, you’ll understand:

What the Model Context Protocol (MCP) is and why it matters.
How MCP powers AI and development tools to communicate in a structured, consistent way.
How Dart integrates MCP through the dart_mcp package and server tools.
Practical examples of how to build an MCP server and client in Dart.
How to get started, including prerequisites and learning resources.

Prerequisites
What is MCP (Model Context Protocol)?
Why MCP Matters for Dart and Flutter Developers
MCP in the Dart Ecosystem
- What Is the dart_mcp Package?
Real-world use cases
How MCP actually works
Getting started, step-by-step
Hands-on example
- Step-by-step explanation
How to Build a Simple MCP Server in Dart
- Step 1: Add Dependency
- Step 2: Create the Server
Example: Creating an MCP Client
MCP vs. Custom HTTP Servers
Best Practices, Safety, and Permissions
Getting Started as a Beginner
Moving Beyond Beginner Level
Conclusion
References

Prerequisites

To follow along with this guide, you should have the following:

Dart SDK 3.9 or later/Flutter 3.35 beta or later installed on your machine.
Basic understanding of async programming in Dart (using async / await).
Familiarity with standard I/O streams (stdin, stdout) since the MCP client communicates through them.
Access to an MCP-compatible server (for example, Dart MCP Server or a custom implementation).
Pub dependencies properly set up with dart_mcp added to your pubspec.yaml.

What is MCP (Model Context Protocol)?

MCP (Model Context Protocol) is a standard that lets AI models (agents) communicate with developer tools, editors, and projects in a structured, permissioned way. Instead of asking an AI to reason about code you paste into chat, MCP lets the AI call specific capabilities (tools) your project exposes, for example, “run analyzer”, “get file contents”, “run tests”, or “search pub.dev”. This turns the AI into a contextual collaborator that can inspect, run, and even modify your codebase in a controlled fashion.

In simpler terms, it’s a protocol that helps AI agents and tools talk to each other. It removes the need for one-off integrations and standardizes how capabilities like “run this tool,” “fetch this file,” or “get these logs” are described and used.

Why MCP Matters for Dart and Flutter Developers

For developers building in Dart and Flutter, MCP opens up new possibilities:

You can build your own AI-driven tools (for example, analyzers, file processors, or code review assistants) that integrate with editors and assistants through MCP.
You can extend your development workflow, letting AI assistants interact directly with your local Dart projects, run commands, analyze files, or trigger Flutter builds.
You can automate tasks within your local dev environment (like linting, dependency analysis, or report generation) without needing a dedicated API server.

It’s not just about AI, it’s also about standardized automation in your toolchain.

MCP in the Dart Ecosystem

The Dart team has started embracing MCP directly through an official experimental package called dart_mcp. This package gives Dart developers the tools to create both MCP servers and MCP clients, enabling two-way communication between your Dart tools and AI assistants or IDEs.

What Is the `dart_mcp` Package?

The dart_mcp package provides APIs to implement MCP servers and clients using Dart. It’s published by labs.dart.dev, which means it’s an official Dart Labs experiment, actively evolving and backed by the Dart team.

Key features:

Build MCP servers that expose tools and capabilities.
Build MCP clients that connect to those servers.
Support for STDIO transport, allowing local, low-latency communication.
Support for Prompts, Resources, and Tools capabilities.
Protocol-aligned structure for initialization, schema validation, and request/response handling.

Limitations (as of version 0.3.3):

HTTP and streamable transports are still experimental.
Authorization and batching aren’t fully supported yet.
The package API may change as it matures.

Real-World Use Cases

These are some of the situations where MCP moves from “cool” to genuinely useful:

Fix a runtime UI bug. The AI inspects runtime logs and the widget tree, then suggests and applies a fix for a RenderFlex overflow.
Add a package and scaffold usage. You can ask the assistant to add charting, and it searches pub.dev, updates pubspec.yaml, runs dart pub get, and generates the basic widget usage.
Automated code review. On each PR, an AI agent runs dart analyze and flutter test, and comments with suggested improvements.
Learning and mentorship. The tool can inspect a learner’s project and then suggest idiomatic Flutter patterns and add unit tests.
Custom dev tools. It can build internal tools: for example, “list all routes and generate a navigation test”, exposed as a capability and callable by the assistant.

How MCP Actually Works

Before we dive into the flow, it’s important to understand what’s happening under the hood. MCP defines how an AI assistant communicates securely with your local environment. It enables structured, permission-based interactions between your IDE, AI assistant, and development tools, without giving the model unrestricted access.

Let’s look at an example:

AI Assistant (LLM)  ⇄  MCP Client (in IDE/agent)  ⇄  Dart/Flutter MCP Server (dart mcp-server)  ⇄  Tools & Codebase

The MCP server runs inside your environment and exposes tools (capabilities).
The MCP client (for example, Gemini CLI, GitHub Copilot, Firebase Studio, Cursor) communicates with the server.
The AI issues structured tool calls. The server executes and returns structured results.

You stay in control, and tools are explicit and permissioned (instead of having ephemeral “give everything to the model” access).

Getting Started, Step by Step

Follow the below instructions to go from zero to a working MCP-enabled project.

1) Prerequisites

First, you’ll need to install Dart SDK 3.9+ and Flutter (if you want to experiment with Flutter runtime introspection). The Dart MCP server requires Dart 3.9 or later.

You can use VS Code, IntelliJ, or another editor. Many clients/plugins will integrate with MCP.

2) Start the Dart & Flutter MCP server locally

You can run the Dart MCP server with the following command:

dart mcp-server

This command launches the MCP server, the component that client tools (like IDEs or AI assistants) connect to in order to communicate with your local environment.

3) Configure an MCP client

You can configure clients like Gemini CLI, Firebase Studio, GitHub Copilot and Cursor to talk to your server. Here’s an example for the Gemini CLI (add to ~/.gemini/settings.json or project .gemini/settings.json):

{
  "mcpServers": {
    "dart": {
      "command": "dart",
      "args": ["mcp-server"]
    }
  }
}

This tells the client to start the dart mcp-server process and use it as a tool provider.

4) Try an easy request from your IDE assistant

Open your project in VS Code (with an AI assistant enabled). Ask something practical, like:

“Find untested functions and create a test file skeleton for them.”

The assistant will use MCP tools to inspect code, run analysis, and can generate test scaffolding for you to review.

5) Build a custom capability (optional)

One of the most powerful aspects of MCP is that you can extend it with your own capabilities. For example, you might want to expose a script that lists all Flutter routes, checks for deprecated APIs, or runs internal code quality checks, all from within your IDE or AI assistant.

In the example below, a simple Dart MCP server registers a custom tool called list_routes. When the client calls this tool, the server runs a function that scans your project for route definitions and returns them as structured data. This lets your AI assistant interact directly with your codebase in a safe, controlled way.

import 'package:dart_mcp_server/dart_mcp_server.dart';

void main() async {
  final server = McpServer();

  // Define a custom capability
  server.registerTool(
    'list_routes',
    (context, params) async {
      // Example logic: extract all route names in your project
      final routes = await extractRoutesFromProject();
      return {'routes': routes};
    },
  );

  await server.start();
}

Future<List<String>> extractRoutesFromProject() async {
  // Your logic here — e.g., scanning lib/ for route definitions
  return ['/', '/login', '/dashboard'];
}

Once registered, your MCP client (for example, Gemini, Cursor, or Copilot) can call this tool just like any built-in capability, enabling the AI assistant to understand your app’s routes or detect outdated APIs.

Beyond custom scripts, you can tailor MCP to your team’s needs by integrating internal linters, CI scripts, or design system checkers. You can also connect it to internal APIs such as analytics or configuration servers, or create domain-specific commands that reflect how your team builds, tests, and deploys projects. This makes MCP not just a protocol but a flexible foundation you can shape around your workflow.

Hands-On Example

Before we look at the code, let’s clarify what it means to expose an MCP capability in Dart. In the MCP world, a capability is simply a tool or function that an AI assistant can call, for example, to analyze code, read a file, or run a build. Exposing a capability means making that tool accessible through a well-defined interface (usually over HTTP or another structured protocol) so the AI or MCP client can request it, execute it, and receive structured results in return.

In this example, you’ll see how to simulate that idea using a small Dart script. Instead of using the full MCP stack, we’ll create a simple local HTTP server that exposes two basic capabilities: analyze, which runs dart analyze on your project, and getFileContent, which reads and returns the contents of a given file.

This shows the same underlying pattern MCP uses: structured requests come in, your server performs an action, and structured responses go back out.

Create a file simple_mcp_server.dart:

// simple_mcp_server.dart
import 'dart:convert';
import 'dart:io';

Future<void> main() async {
  final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 8081);
  print('Simple MCP-like server listening at http://localhost:8081');

  await for (final request in server) {
    try {
      final body = await utf8.decoder.bind(request).join();
      final data = jsonDecode(body) as Map<String, dynamic>;

      final command = data['command'] as String? ?? '';
      if (command == 'analyze') {
        final result = await Process.run('dart', ['analyze']);
        request.response
          ..statusCode = 200
          ..headers.contentType = ContentType.json
          ..write(jsonEncode({'output': result.stdout.toString(), 'exitCode': result.exitCode}));
      } else if (command == 'getFileContent') {
        final path = data['args']?['path'] as String?;
        if (path == null) {
          request.response
            ..statusCode = 400
            ..write(jsonEncode({'error': 'Missing path'}));
        } else {
          final file = File(path);
          if (!await file.exists()) {
            request.response
              ..statusCode = 404
              ..write(jsonEncode({'error': 'File not found'}));
          } else {
            final content = await file.readAsString();
            request.response
              ..statusCode = 200
              ..headers.contentType = ContentType.json
              ..write(jsonEncode({'content': content}));
          }
        }
      } else {
        request.response
          ..statusCode = 400
          ..write(jsonEncode({'error': 'Unknown command'}));
      }
    } catch (e, st) {
      request.response
        ..statusCode = 500
        ..write(jsonEncode({'error': e.toString(), 'stack': st.toString()}));
    } finally {
      await request.response.close();
    }
  }
}

This Dart script creates a simple local HTTP server that listens for JSON commands on port 8081. It accepts specific commands such as "analyze" and "getFileContent", executes corresponding actions on your machine, and returns a JSON response.

This is a simplified demonstration of how an MCP (Model Context Protocol) server handles requests and executes tools or actions.

Let’s go through it piece by piece so you understand the code really well.

1. Imports

import 'dart:convert';
import 'dart:io';

dart:io provides access to file system, processes, and networking features (used here to start the HTTP server and interact with the system).
dart:convert allows encoding and decoding of JSON data (used to parse the incoming request body and send structured JSON responses).

2. Starting the server

final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 8081);
print('Simple MCP-like server listening at http://localhost:8081');

HttpServer.bind starts an HTTP server on the local machine (127.0.0.1) and port 8081. The server will only be accessible from your own computer, not the internet, and the message confirms the server is running and listening for incoming requests.

3. Handling requests

await for (final request in server) {

This continuously listens for incoming HTTP requests. Each request triggers a new iteration of the loop, allowing multiple requests over time.

4. Reading the request body

final body = await utf8.decoder.bind(request).join();
final data = jsonDecode(body) as Map<String, dynamic>;

This reads the full request body (assuming it’s UTF-8 encoded text) and converts the JSON string into a Dart map (data) so it can be accessed programmatically.

Example expected input:

{
  "command": "analyze"
}

5. Parsing and routing the command

final command = data['command'] as String? ?? '';

This extracts the command key from the request body. If it’s missing or null, it defaults to an empty string.

The server uses this value to determine what action to perform.

6. Handling the "analyze" command

if (command == 'analyze') {
  final result = await Process.run('dart', ['analyze']);
  request.response
    ..statusCode = 200
    ..headers.contentType = ContentType.json
    ..write(jsonEncode({'output': result.stdout.toString(), 'exitCode': result.exitCode}));
}

If the command is "analyze", the script runs the terminal command dart analyze using Process.run(). This checks your Dart project for errors, warnings, or lints. The output of that command (stdout) and its exit code are sent back as JSON in the HTTP response.

Expected response example:

{
  "output": "Analyzing project...\nNo issues found!",
  "exitCode": 0
}

7. Handling the "getFileContent" command

else if (command == 'getFileContent') {
  final path = data['args']?['path'] as String?;

This command expects an "args" object containing a "path" key.

Example request:

{
  "command": "getFileContent",
  "args": { "path": "lib/main.dart" }
}

The rest of the block:

if (path == null) {
  request.response
    ..statusCode = 400
    ..write(jsonEncode({'error': 'Missing path'}));
} else {
  final file = File(path);
  if (!await file.exists()) {
    request.response
      ..statusCode = 404
      ..write(jsonEncode({'error': 'File not found'}));
  } else {
    final content = await file.readAsString();
    request.response
      ..statusCode = 200
      ..headers.contentType = ContentType.json
      ..write(jsonEncode({'content': content}));
  }
}

If no path is provided, it returns an HTTP 400 error. If the file doesn’t exist, it returns a 404. And if the file exists, it reads its content and sends it back in JSON format.

Example response:

{
  "content": "void main() { print('Hello World'); }"
}

8. Handling unknown commands

else {
  request.response
    ..statusCode = 400
    ..write(jsonEncode({'error': 'Unknown command'}));
}

If the command field does not match any known options, the server returns an error.

9. Error handling

} catch (e, st) {
  request.response
    ..statusCode = 500
    ..write(jsonEncode({'error': e.toString(), 'stack': st.toString()}));
}

If any unhandled exception occurs (such as invalid JSON or runtime errors), the server catches it. It responds with a 500 status and includes both the error message and stack trace for debugging.

10. Closing the response

finally {
  await request.response.close();
}

Ensures that the response is properly closed after every request to prevent resource leaks.

Summary

This is a local HTTP server that mimics a very basic MCP workflow. It accepts commands over HTTP, performs system or file operations, and returns structured JSON results. It demonstrates how an AI assistant could interact with a Dart environment programmatically (for example, by analyzing code or reading files) through a safe, structured protocol.

How to run it:

Save the file in the root of a Dart project.
Run dart run simple_mcp_server.dart.
In another terminal, test the analyze command:

curl -X POST http://localhost:8081 -H "Content-Type: application/json" -d '{"command":"analyze"}'

You’ll get back the analyzer output as JSON. In a real MCP workflow, the AI client would make similarly structured calls, except those calls are managed by an MCP client and follow the MCP spec for tools/resources/roots. The official Dart MCP server provides many more built-in tools and a full implementation that integrates with supported clients.

How to Build a Simple MCP Server in Dart

In the previous section, we built a simplified, conceptual version of an MCP-like server using plain Dart and HTTP. That example helped illustrate the basic idea: receiving structured requests, executing specific actions, and returning structured results.

Now, let’s take that concept further and see how to build a proper MCP server using the official dart_mcp package. This version follows the real MCP specification and can interact with actual MCP clients, giving you a foundation for extending, testing, or customizing how your development tools communicate with the AI assistant.

Step 1: Add Dependency

Add this to your pubspec.yaml:

dependencies:
  dart_mcp: ^0.3.3

Step 2: Create the Server

import 'package:dart_mcp/server.dart';

class MyServer extends MCPServer with ToolsSupport, ResourcesSupport {
  MyServer()
      : super(Implementation(
          name: 'my-dart-mcp-server',
          version: '1.0.0',
        ));

  @override
  Future<void> initialize() async {
    // Register a simple tool
    registerTool(
      'analyzeCode',
      description: 'Analyze Dart code using the analyzer.',
      inputSchema: {
        'type': 'object',
        'properties': {
          'path': {'type': 'string'}
        },
        'required': ['path']
      },
      callback: (args, extra) async {
        final path = args['path'];
        // You can call `dart analyze` here or integrate analyzer APIs
        return {'message': 'Analyzed project at $path successfully.'};
      },
    );

    await super.initialize();
  }
}

void main() {
  final server = MyServer();
  server.connect(StdioServerTransport());
}

This Dart code defines a basic MCP server using the official dart_mcp package.

It’s a minimal working example that demonstrates how to create a custom MCP server, register a command (“tool”) that AI assistants or clients can call, and expose it over a local connection (using standard input/output, stdio).

Let’s break it down line by line.

1. Import the package

import 'package:dart_mcp/server.dart';

This imports the server-side APIs from the dart_mcp package. These APIs allow you to create and configure an MCP server, register tools (commands) and resources, and handle incoming requests from MCP clients (for example, editors or AI assistants).

2. Create a server class

class MyServer extends MCPServer with ToolsSupport, ResourcesSupport {

This defines a custom class named MyServer that extends MCPServer.

MCPServer is the base class that manages communication, initialization, and capability discovery. The with keywords mix in additional capabilities. ToolsSupport allows you to register tools, callable commands that perform actions. ResourcesSupport allows you to register resources, accessible data like project files or datasets.

So this server supports both tools (commands) and resources (data).

3. The constructor

MyServer()
    : super(Implementation(
        name: 'my-dart-mcp-server',
        version: '1.0.0',
      ));

Here, the constructor passes information about the implementation to the parent MCPServer class.

Implementation is a metadata object that describes the server, including:

name, a unique name for your server, and
version, the version number.

This metadata helps clients identify which MCP server they’re communicating with.

4. Overriding the initialization method

@override
Future<void> initialize() async {

This method runs when the server starts up. It’s where you register tools and resources before the server begins listening for commands.

5. Registering a tool

registerTool(
  'analyzeCode',
  description: 'Analyze Dart code using the analyzer.',
  inputSchema: {
    'type': 'object',
    'properties': {
      'path': {'type': 'string'}
    },
    'required': ['path']
  },
  callback: (args, extra) async {
    final path = args['path'];
    // You can call `dart analyze` here or integrate analyzer APIs
    return {'message': 'Analyzed project at $path successfully.'};
  },
);

This section defines a tool called "analyzeCode".

Let’s explain each part:

'analyzeCode': the tool’s name (how a client identifies it).
description: a short explanation of what the tool does.
inputSchema: a JSON schema that defines what input this tool expects. It expects an object with one property "path", which must be a string.
callback: a function that runs when the client calls this tool.
args contains the client’s input, and you can use args['path'] to access the provided path. In a real implementation, you could call dart analyze or use the Dart analyzer APIs to check the code at that path. The callback returns a response (in this case, a success message).

This tool can later be invoked by a connected MCP client, for example:

{
  "command": "analyzeCode",
  "args": { "path": "lib/" }
}

And the server would respond:

{
  "message": "Analyzed project at lib/ successfully."
}

6. Call the parent initializer

await super.initialize();

This ensures that the base class (MCPServer) performs its own initialization logic after your custom setup (for example, registering built-in tools or preparing internal structures).

7. Main entry point

void main() {
  final server = MyServer();
  server.connect(StdioServerTransport());
}

This is the entry point of the application. It creates an instance of your MyServer class. Then it connects using StdioServerTransport() which allows the server to communicate via standard input/output (stdio), the same mechanism used by local AI assistants and command-line tools.

In practice, this means the server doesn’t need to run an HTTP server. It can talk directly to other local tools that use MCP, such as IDE extensions or AI assistants that launch it.

This kind of MCP server could be connected to an IDE like VS Code or JetBrains via MCP to run Dart analysis automatically. It would let an AI assistant access your local Dart project, analyze files, and return insights, serving as a bridge between your Flutter project and external automation tools.

It’s a simple example that creates a command (analyzeCode) that an MCP client (like an AI assistant) can call. The client will send input through the MCP protocol, and your Dart server responds accordingly.

Connecting to Your MCP Server with a Client

Now that you’ve built a simple MCP server, the next logical step is to see how a client interacts with it. The client is the other half of the equation: it connects to your server, initializes communication, and calls the tools (capabilities) you’ve registered.

The example below shows how to create a basic Dart-based MCP client that talks to the server you built earlier and invokes one of its tools.

import 'package:dart_mcp/client.dart';

void main() async {
  final client = await MCPClient.connectStdioServer(stdin, stdout);
  final initResult = await client.initialize(
    Implementation(name: 'my-client', version: '1.0.0'),
  );

  print('Connected to server: ${initResult.serverCapabilities.tools}');
  final result = await client.callTool('analyzeCode', {'path': 'lib/'});
  print(result);
}

This code creates a simple MCP client that connects to an MCP server (like the one you built earlier) and calls one of its registered tools.

Here’s what it does, step by step:

import 'package:dart_mcp/client.dart';

This imports the client-side API from the dart_mcp package. This lets you connect to an MCP server and call its tools.

final client = await MCPClient.connectStdioServer(stdin, stdout);

This creates a new MCP client and connects to a server using standard input/output (stdio). Again, this is how local tools or AI assistants communicate with MCP servers running on your system.

final initResult = await client.initialize(
  Implementation(name: 'my-client', version: '1.0.0'),
);

This sends an initialization request to the server. The Implementation object identifies this client by name and version. The server responds with its available capabilities (like registered tools and resources).

print('Connected to server: ${initResult.serverCapabilities.tools}');

This prints the list of tools that the server has registered, for example, ["analyzeCode"].

final result = await client.callTool('analyzeCode', {'path': 'lib/'});

This calls the server’s analyzeCode tool, passing {'path': 'lib/'} as the input. The server runs the callback registered for that tool and returns a response.

print(result);

And this prints the result returned by the server (for example: {"message": "Analyzed project at lib/ successfully."}).

Summary:
This client connects to an MCP server over stdio, initializes communication, lists available tools, calls one (analyzeCode), and prints the response. It’s the client-side counterpart of the earlier server example. Together, they demonstrate how two Dart programs can communicate using the MCP protocol.

This connects to the MCP server through stdin/stdout, initializes communication, and calls the analyzeCode tool.

MCP vs. Custom HTTP Servers

If you’ve ever built a simple Dart HTTP server that handles commands like “analyze” or “getFileContent,” you’ve already done something similar to MCP. The difference is that MCP provides a formal structure and protocol that standardizes how such interactions occur.

Instead of manual JSON parsing and ad-hoc commands, the MCP layer handles:

Tool registration and discovery
Schema-based validation
Standardized request and response types
Built-in initialization and capabilities negotiation

So while a custom HTTP approach works for quick experiments, dart_mcp lets you build compliant, future-proof MCP tools that integrate cleanly with editors and assistants.

Best Practices, Safety, and Permissions

Start read-only. Give the assistant tools that read project state first (analyze, read file, run tests). Only enable write actions (edit files, git commit) after you trust the automation.
Review every change. Even if the AI can apply fixes, treat it as a co-author: inspect diffs and run your tests.
Limit scopes. Don’t expose secrets or keys to the MCP server. Use environment separation (dev vs. CI) and explicit capability gating.
Audit logs. Keep logs for MCP calls and changes made by agents so you can trace who did what and when.
Set up team rules. Define team policies for automated edits, for example, “AI can apply formatting and minor lint fixes, but not major architectural changes without human approval.”

Getting Started as a Beginner

If you’re new to this space, here’s a simple roadmap:

Read about MCP basics: Visit the official Dart MCP page to understand what it is and where it fits in your workflow.
Install and explore dart_mcp: Try running one of the examples on pub.dev. Experiment with building your own simple tool.
Connect it with your AI assistant or IDE: Tools like Gemini or VS Code MCP plugins allow you to register your local Dart MCP server in the mcpServers configuration file.
Expand your tools: Build more complex commands like “run tests,” “format code,” “fetch dependencies,” or “generate reports.”
Contribute or follow the Dart Labs repo: MCP support in Dart is evolving rapidly. Keeping up with updates helps you stay ahead.

Moving Beyond Beginner Level

Once you understand the basics:

Start integrating your MCP tools into Flutter development pipelines.
Build an AI-powered assistant that interacts directly with your Flutter project files.
Explore the MCP GitHub discussions and OpenAI’s model context spec for deeper insights.
You can even contribute your own MCP-based package to the community.

Conclusion

The Model Context Protocol is shaping the next generation of developer tools, enabling smarter, AI-driven, and more integrated workflows. As a Dart or Flutter developer, learning MCP now positions you ahead of the curve.

By leveraging the dart_mcp package, you can start building compliant, extensible, and automated tools today, transforming how your development environment interacts with code, analysis, and AI.

References

"Dart and Flutter MCP Server” (official docs)
dart_mcp package on pub.dev
Medium article “Supercharge Your Dart & Flutter Development Experience with the Dart and Flutter MCP Server”
GitHub repository for a Dart MCP server implementation

How to Build a To-Do List MCP Server Using TypeScript – with Auth, Database, and Billing

Shola Jegede — Wed, 22 Oct 2025 19:59:14 +0000

In this tutorial, you’ll build a To-Do list MCP server using TypeScript. You’ll learn how to implement authentication, persistence, and billing, to make the server robust and functional for real users.

By the end, you’ll have a working MCP server that:

Authenticates users with Kinde.
Stores to-do data in a Neon Postgres database.
Enforces billing limits and supports upgrades.
Exposes all these features as MCP tools inside Cursor.

This article will walk you through each step, helping you understand design decisions that you can adapt for your own projects.

What You’ll Learn

Why Go Beyond Basic MCP Servers
What You’ll Build
Prerequisites
Project Setup
Database Setup with Neon PostgreSQL
Authentication with Kinde
MCP Server Implementation (with Billing System Integration)
Testing the Complete System
Troubleshooting
Final MCP Server Architecture
Conclusion
- Next Steps
- Resources

Why Go Beyond Basic MCP Servers?

If you read this freeCodeCamp MCP handbook, you learned how to set up a simple MCP server in TypeScript. That’s useful for learning the protocol, but it doesn’t reflect what you need in production.

A real application requires:

Authentication so each user has their own data and permissions.
Persistence so data is stored in a reliable database.
Billing so you can enforce limits and monetize usage.

Without these, an MCP server is just a demo.

What You’ll Build

In this tutorial, you’ll build a to-do MCP server with TypeScript that includes the essentials of a production-ready backend:

Authentication with Kinde
Database persistence with Neon Postgres
Billing enforcement with a free tier and upgrade path
MCP tool exposure so all of this works seamlessly

By the end, you’ll have an MCP server that feels more like the backend of a SaaS app and a template you can extend for your own ideas.

Prerequisites

Before we start, you'll need:

Accounts & Services (all free to use):

Kinde Account → for authentication and billing
Neon Account → for PostgreSQL database
Node.js (v18+) (download)
Cursor IDE → for MCP integration and tool testing (download)

Development Tools:

Terminal/Command line access
Git (optional, for version control)

Project Setup

First, create a new folder:

mkdir todo-mcp-server
cd todo-mcp-server

Then initialize a Node.js project:

npm init -y

Next, install the dependencies your server will need:

npm install @modelcontextprotocol/sdk @neondatabase/serverless @kinde-oss/kinde-typescript-sdk express jsonwebtoken jwks-client express-session

The @modelcontextprotocol/sdk package gives us everything we need to build and expose MCP servers and tools. We’re using @neondatabase/serverless to connect to a Neon Postgres database, and @kinde-oss/kinde-typescript-sdk handles authentication and billing through Kinde.

We’ll also install express, which makes it easy to define routes and handle middleware. To verify user tokens from Kinde, we’ll use jsonwebtoken together with jwks-client. And finally, express-session will take care of managing session state so users can stay logged in across requests.

Next, set up TypeScript and a few type definitions for development:

npm install -D typescript @types/node @types/express @types/express-session tsx

The typescript package enables TypeScript in your project so you can write strongly typed code. The @types/* packages provide type definitions for Node.js, Express, and the session middleware, giving you better autocomplete and error checking in your editor.

Finally, tsx makes it super easy to run TypeScript files directly without the need to pre-compile them before running your app.

Then create a .env file in your project root and paste these variables:

# Database
DATABASE_URL=postgresql://user:pass@host:port/db

# Kinde Authentication
KINDE_ISSUER_URL=https://your-domain.kinde.com
KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret

# Security
JWT_SECRET=your_secret_key

# Environment
NODE_ENV=development

This stores all the credentials that you’ll be using for this project.

Next, create a tsconfig.json in the project root to tell the TypeScript compiler how to handle your code:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Finally, update your package.json scripts

{
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/server.ts",
    "start": "node dist/server.js",
    "auth-server": "tsx src/kinde-auth-server.ts",
    "setup-db": "tsx src/setup-db.ts"
  }
}

Database Setup with Neon PostgreSQL

To power your to-do MCP server, you’ll use Neon, a serverless PostgreSQL platform. This gives us a fully managed, scalable database without worrying about infrastructure.

1. Connect your Neon Database

Sign up or log in to your Neon account console.
Create a new project.
Copy the connection string, you’ll need it in your .env file.

2. Create your DB File

Inside your project, create a new file in your src/ folder and name it setup-db.ts. This file will create the tables, indexes, and schema your app relies on.

Database Architecture Overview:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   setup-db.ts   │───▶│  Neon Database  │───▶│   PostgreSQL    │
│   (Schema)      │    │   (Serverless)  │    │   (Tables)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘

3. Step-by-Step Breakdown of `setup-db.ts`

Step 1: Imports and Database Connection

Start by importing the packages you’ll need and setting up your database connection:

import { neon } from '@neondatabase/serverless';
import dotenv from 'dotenv';

dotenv.config();

const sql = neon(process.env.DATABASE_URL!);

The dotenv package loads your environment variables from a .env file so you don’t have to hardcode secrets in your code. The neon function connects your app to your Neon Postgres database, and the sql variable gives you a clean, type-safe way to run queries.

At this point, your app has everything it needs to talk to the database.

Step 2: Main Setup Function

Now let’s create a function to handle the database setup process:

async function setupDatabase() {
  console.log('Setting up database schema...');
  try {
    // Database operations here
  } catch (error) {
    console.error('Error setting up database:', error);
    process.exit(1);
  }
}

This function keeps all your schema creation logic in one place, making it easy to manage. It also catches and logs any errors instead of failing silently, so you’ll immediately know if something goes wrong. The console messages give you real-time feedback as the setup runs which is super helpful when you’re debugging or deploying.

Step 3: To-Dos Table

Next, create a table to store all user to-dos:

await sql`
  CREATE TABLE IF NOT EXISTS todos (
    id SERIAL PRIMARY KEY,
    user_id TEXT NOT NULL,
    title TEXT NOT NULL,
    description TEXT,
    completed BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  )
`;

This table holds every user’s tasks. The user_id column links each to-do to the user who created it, while the completed field tracks whether a task is done or still pending. The automatic created_at and updated_at timestamps make it easy to sort tasks or track their history over time.

Step 4: Users Table

Now, let’s define a table to manage user accounts and billing details:

await sql`
  CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    user_id TEXT UNIQUE NOT NULL,
    name TEXT,
    email TEXT,
    subscription_status TEXT DEFAULT 'free' CHECK (subscription_status IN ('free', 'active', 'cancelled')),
    plan TEXT DEFAULT 'free',
    free_todos_used INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  )
`;

This table stores each user’s basic information along with their subscription details. The user_id value comes directly from Kinde during authentication. The subscription_status and free_todos_used columns help you enforce billing tiers and limit how many free tasks a user can create before needing to upgrade.

Step 5: Performance Indexes

Next, let’s add a few indexes to make common database operations faster:

await sql`
  CREATE INDEX IF NOT EXISTS idx_todos_user_id ON todos(user_id)
`;

await sql`
  CREATE INDEX IF NOT EXISTS idx_todos_created_at ON todos(created_at)
`;

await sql`
  CREATE INDEX IF NOT EXISTS idx_users_user_id ON users(user_id)
`;

These indexes help speed up lookups and sorting. The first one lets the database quickly find to-dos that belong to a specific user. The second makes it faster to sort tasks by their creation date. And the last one allows fast lookups of users based on their Kinde user_id.

Step 6: Success Logging

After everything runs, it’s helpful to log a clear summary of what was created:

console.log('✅ Database schema created successfully!');
console.log('📋 Tables created:');
console.log('  - todos (id, user_id, title, description, completed, created_at, updated_at)');
console.log('  - users (id, user_id, subscription_status, plan, free_todos_used, created_at, updated_at)');
console.log('🔍 Indexes created for optimal performance');

These logs give you immediate feedback once the setup completes. They show exactly which tables and indexes were created, making it easy to confirm that your database schema is ready to go and everything ran as expected.

Step 7: Error Handling

try {
} catch (error) {
  console.error('❌ Error setting up database:', error);
  process.exit(1);
}

This handles any database setup errors gracefully.

Step 8: Update your .env file in your project root with your Neon database connection string:

DATABASE_URL=postgresql://username:password@host/database?sslmode=require

Step 9: Function Execution

At the bottom of setup-db.ts, run the function:

setupDatabase();

This immediately executes the database setup when the script runs.

Now, run this command in your CLI:

npm run setup-db

Expected output:

🚀 Setting up database schema...
✅ Database schema created successfully!
📋 Tables created:
  - todos (id, user_id, title, description, completed, created_at, updated_at)
  - users (id, user_id, subscription_status, plan, free_todos_used, created_at, updated_at)
🔍 Indexes created for optimal performance

4. Full `setup-db.ts` File

You can view the complete implementation of the setup-db.ts file in the GitHub repo and copy it directly into your project.

Authentication with Kinde

To secure your MCP server, you’ll use Kinde, an authentication provider that makes it easy to handle logins, user sessions, and tokens.

You’ll also connect Kinde to your Neon database so new users are automatically created when they log in.

1. Create a Kinde Application

Go to the Kinde Dashboard.
Create a new application.
Note down these values (you’ll use them shortly):
- Domain: https://your-domain.kinde.com
- Client ID: your-client-id
- Client Secret: your-client-secret

2. Configure Kinde Settings

In your Kinde dashboard, save these URLs as your:

Redirect URL → http://localhost:3000/callback
Logout URL → http://localhost:3000

3. Environment Variables

Update the .env file in your project root with the credentials from your Kinde Dashboard:

KINDE_ISSUER_URL=https://your-domain.kinde.com
KINDE_CLIENT_ID=your_client_id
KINDE_CLIENT_SECRET=your_client_secret

4. Create the Kinde Auth Server

You’ll build an Express server (src/kinde-auth-server.ts) to handle authentication. This server will manage OAuth login and logout with Kinde, store user sessions, and automatically create or update users in your Neon database whenever they sign in.

4.1: Dependencies and Setup

Start by importing the packages you’ll need:

import express from 'express';
import session from 'express-session';
import { createKindeServerClient, GrantType, SessionManager } from '@kinde-oss/kinde-typescript-sdk';
import jwt from 'jsonwebtoken';
import dotenv from 'dotenv';
import { neon } from '@neondatabase/serverless';

The express import powers the web server that will handle authentication routes. express-session manages user sessions so you can persist login state between requests. The @kinde-oss/kinde-typescript-sdk package is the official Kinde SDK, which handles OAuth flows and user authentication.

You’ll use jsonwebtoken to decode and verify user tokens, while dotenv loads environment variables from your .env file. Finally, @neondatabase/serverless connects your server to the Neon Postgres database where user data will be stored.

4.2: Connect to Your Database

const sql = neon(process.env.DATABASE_URL!);

This initializes a type-safe SQL client using your DATABASE_URL.

4.3: Extend login Session

declare module 'express-session' {
  interface SessionData {
    accessToken?: string;
    idToken?: string;
    userInfo?: any;
    userName?: string;
    userEmail?: string;
  }
}

This extends express-session types so you can store Kinde tokens and user info directly in the session.

4.4: Configure Sessions

Now, let’s configure session management so users can stay logged in across requests:

app.use(session({
  secret: process.env.JWT_SECRET || 'your_jwt_secret_key',
  resave: true,
  saveUninitialized: true,
  cookie: { 
    secure: false,
    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
    httpOnly: true,
    sameSite: 'lax'
  }
}));

The secret value is used to sign and verify session cookies, ensuring that sessions can’t be tampered with. The cookie settings keep users logged in for up to 7 days and make sure session tokens persist even after a browser refresh.

Setting httpOnly helps protect against cross-site scripting (XSS) attacks, while sameSite: 'lax' allows users to log in across different origins without breaking authentication.

4.5: Create a Session Manager Factory

Next, you’ll define a small helper function to manage session data for each request:

const createSessionManager = (req: any): SessionManager => ({
  getSessionItem: async (key: string) => req.session?.[key],
  setSessionItem: async (key: string, value: any) => {
    if (!req.session) req.session = {};
    req.session[key] = value;
  },
  removeSessionItem: async (key: string) => {
    if (req.session) delete req.session[key];
  },
  destroySession: async () => {
    req.session = {};
  }
});

This function creates a session manager that’s tied to each request. It provides a consistent way to store, retrieve, and clear session data which is exactly what the Kinde SDK needs to keep track of tokens and user info during authentication.

4.6: Create the Kinde Client

Next, set up the Kinde client that will handle the OAuth login and logout flow:

const kindeClient = createKindeServerClient(GrantType.AUTHORIZATION_CODE, {
  authDomain: process.env.KINDE_ISSUER_URL!,
  clientId: process.env.KINDE_CLIENT_ID!,
  clientSecret: process.env.KINDE_CLIENT_SECRET!,
  redirectURL: '',
  logoutRedirectURL: '',
});

This connects your app to Kinde using the Authorization Code grant type which is the most secure option for server-side applications like this one.

The redirectURL and logoutRedirectURL define where users should be sent after logging in or out.

4.7: Create the Home Page Route (GET /)

Then you’ll define a basic route for your home page that checks whether a user is logged in:

app.get('/', (req, res) => {
  const token = req.session?.accessToken;
  const userInfo = req.session?.userInfo;

  if (token) {
    // Show logged-in state with tokens
  } else {
    // Show login button
  }
});

This route reads the session to determine if a user is authenticated. If a token exists, you can display their account details or dashboard. Otherwise, you’ll show a login button that directs them to Kinde’s sign-in page.

4.8: Create the Login Route (GET /login)

Now, add a route that starts the OAuth login process:

app.get('/login', async (req, res) => {
  try {
    const sessionManager = createSessionManager(req);
    const loginUrl = await kindeClient.login(sessionManager);
    res.redirect(loginUrl.toString());
  } catch (error) {
    console.error('Login error:', error);
    res.status(500).send('Login failed');
  }
});

When users visit this route, your app uses the Kinde client to generate a secure login URL and redirects them to Kinde’s hosted login page. Once they log in, Kinde will send them back to your callback route with the necessary tokens.

4.9: OAuth Callback Route (GET /callback)

This is where Kinde redirects users back after login. First, you’ll get the authorization code from Kinde for token exchange:

const fullUrl = `http://${req.headers.host}${req.url}`;
const url = new URL(fullUrl);
const code = url.searchParams.get('code');

Next, you’ll exchange this code for tokens that will be needed for API calls:

const tokenResponse = await fetch(`${process.env.KINDE_ISSUER_URL}/oauth2/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: process.env.KINDE_CLIENT_ID!,
    client_secret: process.env.KINDE_CLIENT_SECRET!,
    code: code,
    redirect_uri: 'http://localhost:3000/callback',
  }),
});

Then, you’ll store these tokens in the session for future requests so users don't need to login every time:

req.session.accessToken = tokenData.access_token;
req.session.idToken = tokenData.id_token;
req.session.userInfo = tokenData;

The next thing you’ll do is to extract the user’s information from JWT and then store this in your database

const user = JSON.parse(Buffer.from(idToken.split('.')[1], 'base64').toString());
req.session.userName = user.given_name || user.name || 'User';
req.session.userEmail = user.email || 'user@example.com';

Finally, add this code that will automatically create or update the user in the database so your MCP server can track to-dos and billing:

const existingUser = await sql`SELECT * FROM users WHERE user_id = ${userId}`;

if (existingUser.length === 0) {
  await sql`
    INSERT INTO users (user_id, name, email, subscription_status, plan, free_todos_used)
    VALUES (${userId}, ${userName}, ${userEmail}, 'free', 'free', 0)
  `;
} else {
  await sql`
    UPDATE users 
    SET name = ${userName}, email = ${userEmail}
    WHERE user_id = ${userId}
  `;
}

4.10: Create the Logout Route (GET /logout)

app.get('/logout', async (req, res) => {
  try {
    req.session.destroy((err) => {
      if (err) {
        console.log('Session destroy error:', err);
      }
      res.redirect('/');
    });
  } catch (error) {
    console.error('Logout error:', error);
    res.status(500).send('Logout failed');
  }
});

This route simply destroys the user’s session, removing all stored tokens and user information. Once the session is cleared, it redirects the user back to the home page, effectively logging them out of the app.

5. Complete Authentication Flow

1. User visits / → sees login button.
2. Clicks login → goes to Kinde.
3. Logs in → redirected back to /callback.
4. Callback exchanges code for tokens.
5. Tokens stored in session.
6. User is created/updated in database.
7. User can now access the MCP server.

6. Why This Matters

By placing Kinde in front of your MCP server, you get a secure and seamless authentication layer without the extra trouble of handling passwords or tokens manually. Your users can log in safely, and their sessions persist across page refreshes without the need to log in again each time they revisit your app.

Every new user who signs in is automatically added to your Neon database, making it easy to track accounts and usage. This setup also lays the groundwork for more advanced features later on, like enforcing billing limits or managing user-specific to-dos.

7. Key Connections

Session ↔ Database: Sync user data
Kinde ↔ Session: Tokens flow from Kinde to session storage
Session ↔ MCP: Tokens passed into the server for access control
Database ↔ MCP: User billing + to-dos read from Neon

8. Full `kinde-auth-server.ts` File

You can view the complete implementation of the kinde-auth-server.ts file in the GitHub repo and copy it directly into your project.

MCP Server Implementation (with Billing System Integration)

Now it’s time to create the main file for your MCP server. This file acts as the entry point, wiring up your database, authentication, tool handlers, and overall flow into a single server.

1. Create Your File

Inside your project, create a new file:

src/server.ts

This file will contain the full implementation of your MCP server.

2. Project Setup and Imports

At the top of the file, import the dependencies you’ll need:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { neon } from '@neondatabase/serverless';
import jwt from 'jsonwebtoken';
import fs from 'fs';
import path from 'path';

Each import in your MCP server has a specific purpose. The Server class is the foundation that powers your entire implementation. It listens for requests, manages responses, and keeps track of all registered tools. The StdioServerTransport handles communication between your MCP server and other tools through standard input and output, which is exactly how Cursor connects behind the scenes.

The CallToolRequestSchema and ListToolsRequestSchema act as validators, ensuring every incoming request follows the correct structure before it’s processed. This reduces errors and keeps communication between your tools and the MCP client consistent.

neon connects your server to the Neon PostgreSQL database, providing a clean way to manage persistent data like users and to-dos. The jsonwebtoken library decodes and verifies tokens from Kinde, letting you identify and authenticate users securely.

fs is used to read and write authentication tokens locally, which means users don’t need to log in every time. Finally, path helps manage file paths cleanly across different systems, keeping everything organized and portable.

Together, these imports form the backbone of your server’s logic, handling authentication, database access, and reliable communication with Cursor.

3. Database Connection and Configuration

Next, configure your database connection and token storage:

const sql = neon(process.env.DATABASE_URL!);
const TOKEN_FILE = '.auth-token';

The sql constant creates a live connection to your Neon PostgreSQL database using the DATABASE_URL environment variable. Think of it as the bridge that lets your MCP server talk to your database with every query, insert, and update running through this connection.

It’s what allows your server to persist user data, to-dos, and billing information reliably without having to manage complex configurations manually.

The TOKEN_FILE constant, on the other hand, acts as a lightweight local storage system for authentication tokens. Whenever a user logs in, their token is saved here so they don’t have to reauthenticate every time they restart the server.

It’s a simple but effective way to maintain session continuity, especially during local development or testing.

4. Authentication System

To manage tokens, you’ll add three helper functions:

4.1. Get Stored Token

function getStoredToken(): string | null {
  try {
    if (fs.existsSync(TOKEN_FILE)) {
      return fs.readFileSync(TOKEN_FILE, 'utf8').trim();
    }
  } catch (error) {
    console.error('Error reading token file:', error);
  }
  return null;
}

Retrieves a saved JWT token from the local file system.

4.2. Store Token

function storeToken(token: string): void {
  try {
    fs.writeFileSync(TOKEN_FILE, token);
  } catch (error) {
    console.error('Error storing token:', error);
  }
}

Stores a new JWT token locally so authentication persists across server restarts.

4.3. Decode JWT

function decodeJWT(token: string): any {
  try {
    return jwt.decode(token);
  } catch (error) {
    console.error('Error decoding JWT:', error);
    return null;
  }
}

Decodes JWTs to extract user info such as ID, email, and subscription status.

5. Core Helper Functions

5.1. Check Billing Status

async function getKindeBillingStatus(userId: string, accessToken: string): Promise<{ plan: string; features: any; canCreate: boolean; reason?: string }> {
  try {
    const decoded = jwt.decode(accessToken) as any;
    console.log('🔍 JWT Token data for user:', userId, 'Decoded:', decoded);

    const subscription = await sql`
      SELECT * FROM users 
      WHERE user_id = ${userId}
    `;

    if (subscription.length === 0) {
      await sql`
        INSERT INTO users (user_id, name, email, subscription_status, plan, free_todos_used)
        VALUES (${userId}, ${decoded.given_name || decoded.name || 'User'}, ${decoded.email || 'user@example.com'}, 'free', 'free', 0)
      `;
      console.log('👤 New user created:', decoded.given_name || decoded.name, decoded.email);
    }

    const freeTodosUsed = subscription.length > 0 ? subscription[0].free_todos_used : 0;

    if (freeTodosUsed < 1) {
      return {
        plan: 'free',
        features: { maxTodos: 1, used: freeTodosUsed },
        canCreate: true,
        reason: `Free tier - ${1 - freeTodosUsed} todo remaining`
      };
    }

    return {
      plan: 'free',
      features: { maxTodos: 1, used: freeTodosUsed },
      canCreate: false,
      reason: 'You have used your free todo. Please upgrade your plan at  to create more todos.'
    };
  } catch (error) {
    console.error('Error checking Kinde billing:', error);
    return {
      plan: 'free',
      features: { maxTodos: 1 },
      canCreate: false,
      reason: 'Error checking billing status'
    };
  }
}

This checks a user's billing status and enforces a 1-todo free tier. It also auto-creates a user in the database if it doesn’t exist.

5.2. Check To-Do Permission

async function canCreateTodo(userId: string, accessToken: string): Promise<boolean> {
  const billingStatus = await getKindeBillingStatus(userId, accessToken);
  return billingStatus.canCreate;
}

This is a simple wrapper that returns a boolean for permission checks.

6. Core Server Implementation

Initialize your MCP server:

const server = new Server(
  {
    name: 'todo-mcp-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

This declares a new MCP server with the capability to register tools.

7. Register Tools

Every tool that your Cursor IDE can use needs to be listed so it knows what’s available. In this part of the server setup, you’re registering all the tools that your MCP server will expose. Think of it like giving Cursor a menu of what your backend can do.

Here’s how that looks in code:

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'login',
        description: 'Get authentication URL for Kinde login',
        inputSchema: {
          type: 'object',
          properties: {},
        },
      },
      // ... more tools
    ],
  };
});

Tools you’ll create include:

Authentication → login, save_token, logout
To-Do Management → list_todos, create_todo, update_todo, delete_todo
Billing → refresh_billing_status

8. Tool Handlers

Each tool in your MCP server has its own handler. The handler checks if the user is authenticated, talks to the database to perform the request, and returns a clean, structured response that Cursor can display.

This keeps the server organized, secure, and easy to extend later.

8.1. Login Tool

The login tool is responsible for starting the authentication flow with Kinde. When users call it, the server returns a short message explaining how to sign in and store their token.

Once logged in, it lists a few commands that they user can try.

Here’s the handler:

case 'login': {
  return {
    content: [
      {
        type: 'text',
        text: `🔐 **Authentication Required**

To use this MCP server, you need to authenticate with Kinde:

1. **Open your browser** and go to: 
2. **Click "Login with Kinde"** to authenticate
3. **Copy your ID Token** from the page
4. **Use the save_token tool** to store it

**Note:** Make sure the Kinde auth server is running:
\\`\\`\\`bash
npm run auth-server
\\`\\`\\`

After authentication, you can use commands like:
- \\`list todos\\` - List your todos
- \\`create todo\\` - Create a new todo
- \\`refresh billing status\\` - Check your plan status`,
      },
    ],
  };
}

8.2. Save Token Tool

The save_token tool handles storing the user’s authentication token locally so they don’t need to re-authenticate each time they use the MCP server.

Here’s the handler:

case 'save_token': {
  const { token } = args as { token: string };
  storeToken(token);
  return {
    content: [
      {
        type: 'text',
        text: '✅ Token saved successfully! You can now use commands like "list todos" and "create todo" without providing the token each time.',
      },
    ],
  };
}

When a user runs this command and passes in their token, the server saves it to a local file using the storeToken() function. From then on, every other command (like list todos, create todo, or refresh billing status) can automatically authenticate using that stored token.

This small step makes the development flow smoother and keeps authentication persistent across sessions.

8.3. List To-Dos Tool

The list_todos tool retrieves all to-dos that belong to the currently authenticated user. It first checks for a stored authentication token and decodes it to identify the user. If the token is missing or invalid, it asks the user to log in again.

Here’s the handler:

case 'list_todos': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please:\\n1. Type "login" to get the authentication URL\\n2. Complete login at \\n3. Copy your token and use "save_token" to store it\\n4. Then try "list todos" again',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again using the "login" command.',
        },
      ],
    ];
  }

  const todos = await sql`
    SELECT * FROM todos 
    WHERE user_id = ${decoded.sub} 
    ORDER BY created_at DESC
  `;

  if (todos.length === 0) {
    return {
      content: [
        {
          type: 'text',
          text: '📝 No todos found. Create your first todo using "create todo"!',
        },
      ],
    ];
  }

  const todosList = todos.map((todo: any) => 
    `**${todo.id}.** ${todo.title}${todo.description ? ` - ${todo.description}` : ''} ${todo.completed ? '✅' : '⏳'}`
  ).join('\\n');

  return {
    content: [
      {
        type: 'text',
        text: `📝 **Your Todos (${todos.length}):**\\n\\n${todosList}`,
      },
    ],
  };
}

Results from this tool are formatted for easy reading in the MCP client, showing each task’s title, description, and completion status. If there are no to-dos yet, it simply prompts the user to create one.

8.4. Create To-Do Tool

The create_todo tool lets authenticated users add new to-dos to their list. It starts by verifying that a valid token exists, ensuring only logged-in users can create tasks. If the token is present, it checks billing limits otherwise, it instructs the user to log in again.

Here’s the handler:

case 'create_todo': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please login first.',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again.',
        },
      ],
    ];
  }

  const { title, description, completed } = args as { 
    title: string; 
    description?: string; 
    completed?: boolean; 
  };

  // Check billing status before creating todo
  const canCreate = await canCreateTodo(decoded.sub, token);
  if (!canCreate) {
    const billingStatus = await getKindeBillingStatus(decoded.sub, token);
    return {
      content: [
        {
          type: 'text',
          text: `🚫 **Cannot create todo**

${billingStatus.reason}

**Upgrade your plan:** >,
        },
      ],
    ];
  }

  const result = await sql`
    INSERT INTO todos (user_id, title, description, completed)
    VALUES (${decoded.sub}, ${title}, ${description || null}, ${completed || false})
    RETURNING *
  `;

  // Update free todos used count
  await sql`
    UPDATE users 
    SET free_todos_used = free_todos_used + 1 
    WHERE user_id = ${decoded.sub}
  `;

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          todoId: result[0].id,
          message: 'Todo created successfully',
          title: result[0].title,
          description: result[0].description,
          completed: result[0].completed
        }, null, 2),
      },
    ],
  };
}

If the user has hit their limit after calling this tool, it returns a clear message explaining why and provides a link to upgrade their plan.

8.5. Update To-Do Tool

The update_todo tool allows an authenticated user to modify an existing to-do’s title, description, or completion status. It first checks for a valid token and decodes it to identify the user. If authentication fails, the tool instructs the user to log in again.

Here’s the handler:

case 'update_todo': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please login first.',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again.',
        },
      ],
    ];
  }

  const { todoId, title, description, completed } = args as { 
    todoId: number; 
    title?: string; 
    description?: string; 
    completed?: boolean; 
  };

  const result = await sql`
    UPDATE todos 
    SET 
      title = COALESCE(${title || null}, title),
      description = COALESCE(${description || null}, description),
      completed = COALESCE(${completed !== undefined ? completed : null}, completed),
      updated_at = CURRENT_TIMESTAMP
    WHERE id = ${todoId} AND user_id = ${decoded.sub}
    RETURNING *
  `;

  if (result.length === 0) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Todo not found or you do not have permission to update it.',
        },
      ],
    ];
  }

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          message: 'Todo updated successfully',
          todo: result[0]
        }, null, 2),
      },
    ],
  };
}

Once the token is verified, the server updates the specified to-do in the database, using COALESCE to leave any fields unchanged if no new value is provided. The updated_at timestamp is refreshed automatically.

If the to-do doesn’t exist or the user doesn’t have permission to modify it, the tool returns an error message. Otherwise, it responds with the updated to-do in a clean JSON format:

8.6. Delete To-Do Tool

The delete_todo tool allows an authenticated user to remove a specific to-do. It first checks for a valid token and decodes it to identify the user. If the token is missing or invalid, the tool instructs the user to log in again.

Here’s the handler:

case 'delete_todo': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please login first.',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again.',
        },
      ],
    ];
  }

  const { todoId } = args as { todoId: number };

  const result = await sql`
    DELETE FROM todos 
    WHERE id = ${todoId} AND user_id = ${decoded.sub}
    RETURNING *
  `;

  if (result.length === 0) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Todo not found or you do not have permission to delete it.',
        },
      ],
    ];
  }

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          message: 'Todo deleted successfully',
          deletedTodo: result[0]
        }, null, 2),
      },
    ],
  };
}

This ensures users can only delete their own tasks, keeps the response structured for easy consumption in Cursor, and provides immediate confirmation of the deletion.

8.7. Refresh Billing Status Tool

The refresh_billing_status tool allows an authenticated user to force a fresh check of their billing status from Kinde. It first verifies that a valid token exists and decodes it to identify the user. If the token is missing or invalid, the tool instructs the user to log in again.

Here’s the handler:

case 'refresh_billing_status': {
  const token = getStoredToken();
  if (!token) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ No authentication token found. Please login first.',
        },
      ],
    ];
  }

  const decoded = decodeJWT(token);
  if (!decoded || !decoded.sub) {
    return {
      content: [
        {
          type: 'text',
          text: '❌ Invalid token. Please login again.',
        },
      ],
    ];
  }

  console.log('🔄 Force refreshing billing status for user:', decoded.sub);
  const billingStatus = await getKindeBillingStatus(decoded.sub, token);

  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({
          success: true,
          message: 'Billing status refreshed successfully!',
          kindeBilling: {
            plan: billingStatus.plan,
            features: billingStatus.features,
            canCreate: billingStatus.canCreate,
            reason: billingStatus.reason,
            upgradeUrl: '',
            selfServicePortal: '',
            lastChecked: new Date().toISOString()
          }
        }, null, 2),
      },
    ],
  };
}

This tool ensures that users always have an up-to-date view of their subscription status and usage limits, providing all necessary information to decide whether they need to upgrade their plan.

8.8. Logout Tool

The logout tool lets a user end their session by clearing the locally stored authentication token. When called, it checks if the token file exists and deletes it. If successful, the tool confirms that the user has been logged out.

Here’s the handler:

case 'logout': {
  try {
    if (fs.existsSync(TOKEN_FILE)) {
      fs.unlinkSync(TOKEN_FILE);
    }
    return {
      content: [
        {
          type: 'text',
          text: '✅ Logged out successfully. Authentication token cleared.',
        },
      ],
    ];
  } catch (error) {
    return {
      content: [
        {
          type: 'text',
          text: '⚠️ Logout completed, but there was an issue clearing the token file.',
        },
      ],
    };
  }
}

This ensures that the session ends cleanly, preventing further use of the MCP server until the user logs in again. It also provides immediate feedback so the user knows the logout process succeeded or if there were minor issues.

9. Full `server.ts` File

You can view the complete implementation of the server.ts file in the GitHub repo and copy it directly into your project.

10. Data Flow & Integration

Now that you’ve wired up authentication, database persistence, and billing checks, let’s step back and look at how everything fits together.

Authentication Flow:

User clicks Login with Kinde.
They are redirected to the Kinde Auth URL.
Kinde issues a JWT token after successful login.
The user copies this token and runs “save_token: ” in the Cursor Chat to store it.
The token is stored in the user’s session.
All future requests include the token for validation.

To-do Flow:

User sends a request (for example, to “create todo” to create a new todo).
The server checks the session for a valid token.
The server verifies the user’s billing plan and usage limits.
If valid, the request hits the Neon Postgres database.
Usage counters are updated and a success response is returned.

Complete Data Flow:

User Input 
   → MCP Server 
      → Authentication Check
         → Billing Check
            → Database Operation
               → Response

Diagram:

flowchart LR
    A[User Input] --> B[MCP Server]
    B --> C{Authenticated?}
    C -- No --> D[Reject Request]
    C -- Yes --> E{Billing OK?}
    E -- No --> F[Reject Request]
    E -- Yes --> G[Database Operation]
    G --> H[Update Usage + Return Response]

This overview shows how the different components work together. Each feature you’ve added (authentication, billing, and persistence) acts as a checkpoint in the request flow.

11. Error Handling & Security

Authentication Security:

JWT Validation: Every request validates JWT token
User Isolation: Users can only access their own to-dos
Token Storage: Tokens are stored locally, not in your database

Database Security:

SQL Injection Prevention: Your MCP server uses parameterized queries
User Scoping: All queries are filtered by user_id
Permission Checks: Every operation validates user ownership

Error Handling:

try/catch returns safe error messages

12. Testing & Deployment

Finally, start the MCP server:

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('Todo MCP server running on stdio');
}

main().catch((error) => {
  console.error('Fatal error in main():', error);
  process.exit(1);
});

Test it by running:

npm run dev

In Cursor, you can now try commands like:

login
save_token: <your-jwt-token>
list todos
create todo
refresh billing status
logout

Testing the Complete System

1. Start the Services

# Terminal 1: Start MCP Server
npm run dev

# Terminal 2: Start Kinde Auth Server
npm run auth-server

2. Configure Cursor MCP

In your Cursor project:

Go to Settings → Tools & MCP → New MCP Server
Edit the ~/.cursor/mcp.json and paste this code below

{
  "mcpServers": {
    "todo-mcp-server": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/path/to/your/todo-mcp-server",
      "env": {
        "DATABASE_URL": "your-neon-connection-string",
        "KINDE_ISSUER_URL": "",
        "KINDE_CLIENT_ID": "your-client-id",
        "KINDE_CLIENT_SECRET": "your-client-secret",
        "JWT_SECRET": "your-jwt-secret-key",
        "NODE_ENV": "development"
      }
    }
  }
}

3. Test the Complete Flow

Open your Cursor chat window and test MCP commands:

login → Get authentication URL
save_token → Save your token gotten from Kinde
list to-dos → List to-dos
create to-do - Create a to-do
refresh billing status - Check billing

Troubleshooting

Even with everything set up correctly, you might run into issues. Here are some common problems and how to fix them.

1. MCP Server Not Detected

If Cursor can’t see your server:

Double-check the syntax of your ~/.cursor/mcp.json file.
Make sure all file paths in mcp.json are absolute paths (not relative).
Restart Cursor after making changes to the config file.

2. Database Connection Issues

If your Neon database won’t connect:

Confirm your DATABASE_URL environment variable is correctly formatted.
Log into the Neon dashboard and make sure your database is active and not paused.
If you’re using SSL, verify that the SSL mode matches Neon’s connection settings.

3. Kinde Authentication Problems

If login isn’t working as expected:

In your Kinde dashboard, make sure the redirect URLs are set correctly (for example, http://localhost:3000).
Double-check that your client ID and client secret are correct.
Ensure your auth server is running locally on port 3000 before attempting login.

4. Token Errors

If you’re getting token-related errors:

Confirm the token you’re saving is in JWT format (three dot-separated parts).
Make sure the token hasn’t expired.
Use the ID token provided by Kinde, not the access token.

Following these steps should resolve most issues you’ll run into when setting up your MCP server with Cursor, Neon, and Kinde.

Final MCP Server Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Cursor IDE    │    │   MCP Server     │    │  Kinde Auth     │
│                 │◄──►│                  │◄──►│   Server        │
│ - MCP Tools     │    │ - Todo CRUD      │    │ - OAuth Flow    │
│ - Chat Interface│    │ - Billing Check  │    │ - Token Storage │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │ Neon PostgreSQL │
                       │                 │
                       │ - Users Table   │
                       │ - Todos Table   │
                       │ - Billing Data  │
                       └─────────────────┘

Conclusion

You’ve just built a fully functional MCP server with:

Authentication → secure logins with Kinde
Data persistence → to-dos stored in Neon
Billing enforcement → usage limits + upgrade path
Tool exposure → MCP tools accessible in Cursor

This foundation is flexible enough to power more advanced apps while keeping the core flow simple and secure.

Next Steps

Here are some ideas to extend what you’ve built:

Role-based access control (RBAC): create admin vs normal user permissions (see my two-part RBAC guide for reference).
Billing tiers: offer free, pro, and enterprise plans with different limits.
Features: add search, tags, or sharing to to-dos.
Deployment: run the service on a cloud platform with HTTPS and a production-grade database.

Resources

You can find the complete source code for this tutorial in this GitHub repository. If it helped you in any way, consider giving it a star (⭐) to show your support!

Also, if you found this tutorial valuable, feel free to share it with others who might benefit from it. I’d really appreciate your thoughts, you can mention me on X @wani_shola or connect with me on LinkedIn.

How to Fix the Python ENOENT Error When Setting Up MCP Servers – A Complete Guide

Idris Olubisi — Fri, 08 Aug 2025 17:49:04 +0000

Getting the "spawn python ENOENT" error while setting up an MCP (Model Context Protocol) server on macOS can be frustrating. But don't worry – in this tutorial, I'll guide you through fixing it by rebuilding your Python virtual environment.

By the end, you'll have a fully functional MCP server integrated with Claude Desktop in about 10 minutes. This solution applies to any MCP setup facing this standard error after Python upgrades.

What Causes the ENOENT Error?
Prerequisites
How to Diagnose Your Broken Virtual Environment
How to Completely Rebuild Your Virtual Environment
How to Install MCP Server Dependencies
How to Locate Your Server Files
How to Test Your Server Setup
How to Configure Claude Desktop
How to Restart Claude Desktop and Test Integration
Understanding MCP Server Capabilities
Alternative Installation Methods
- Method 1: Direct Package Installation
- Method 2: Using UV Package Manager
How to Prevent Future ENOENT Errors
Troubleshooting Common Issues
Conclusion

What Causes the ENOENT Error?

The ENOENT (Error NO ENTry) error means your system can’t locate the Python executable at the specified path. This occurs when the file is missing or inaccessible.

On macOS, this typically happens when:

You've upgraded Python through Homebrew
The brew cleanup command removed old Python versions
Your virtual environment's symlinks now point to non-existent files

What makes this particularly challenging is that your virtual environment folder still exists – it looks fine from the outside, but the Python executable inside is completely broken.

When MCP servers try to spawn Python processes using these broken paths, you get the dreaded ENOENT error. This affects any Python-based MCP server, whether you're building custom tools, connecting to APIs, or working with file systems.

Prerequisites

To follow this tutorial, you'll need:

macOS with Homebrew installed
Python 3.10 or higher
An MCP server repository cloned locally
Claude Desktop installed
Basic familiarity with terminal commands and Python virtual environments

If you haven't cloned an MCP server repository yet, you can start with any open-source MCP server. For this tutorial, I'll use generic examples that work with any MCP setup:

git clone https://github.com/your-username/your-mcp-server.git
cd your-mcp-server

How to Diagnose Your Broken Virtual Environment

First, you need to confirm that your virtual environment is actually the problem. Open your terminal and navigate to your MCP directory:

cd /path/to/your/mcp-server

Now check if your Python executable exists:

ls -la venv/bin/python*

If you see broken symlinks or get "No such file or directory" errors, you've found your problem. You might see output like:

lrwxr-xr-x  1 username  staff  16 Jan  1 12:00 python -> /usr/local/bin/python3.11
lrwxr-xr-x  1 username  staff  16 Jan  1 12:00 python3 -> /usr/local/bin/python3.11

But when you try to run these Python executables:

./venv/bin/python --version

You'll get an error because the target files no longer exist. This confirms your virtual environment is broken and needs rebuilding.

How to Completely Rebuild Your Virtual Environment

The most reliable solution is to rebuild your virtual environment from scratch. This ensures all paths and dependencies are correctly configured for your current Python installation.

Here's your step-by-step rebuild process:

# Make sure you're in the MCP server directory
cd /path/to/your/mcp-server

# Remove the corrupted virtual environment
rm -rf venv

# Create a fresh virtual environment
python3 -m venv venv

# Activate the new environment
source venv/bin/activate

You should now see (venv) in your terminal prompt, indicating the virtual environment is active. This prefix confirms you're working within the isolated Python environment.

How to Install MCP Server Dependencies

With your fresh virtual environment active, install the MCP server and its dependencies. The exact installation command depends on your specific MCP server, but typically follows one of these patterns:

# For package-based installation
pip install -e .

# Or for requirements file
pip install -r requirements.txt

# Or for specific MCP frameworks
pip install fastmcp

Common MCP server dependencies include:

FastMCP for the server framework
JSON-RPC libraries for communication protocols
HTTP clients for API integrations
File system utilities for local operations

The installation process displays all packages as they install. Don't worry if you see deprecation warnings – they're normal and won't affect functionality.

How to Locate Your Server Files

After installation, identify where your main server file lives. Run this command to find all server.py files:

find . -name "server.py" -type f

You may see results like:

./server.py (in the root directory)
./src/server.py (in a source directory)
./mcp_server/server.py (in a package directory)

Check your current directory structure:

ls -la

Look for the main server entry point. Most MCP servers follow standard Python project structures with either a root-level server file or one nested in a package directory.

How to Test Your Server Setup

Now you’ll want to test your server to ensure it's working correctly. Start with the main server file you identified:

python server.py

If this is the correct server and everything is configured correctly, you'll see output similar to:

╭─ MCP Server ───────────────────────────────────────────────────────────────╮
│ 🖥️  Server name: Example-MCP                                              │
│ 📦 Transport: STDIO                                                        │
│ 🤝 Protocol: JSON-RPC                                                      │
╰────────────────────────────────────────────────────────────────────────────╯
[INFO] Starting MCP server with transport 'stdio'
[INFO] Server ready for connections

This output confirms your MCP server is working correctly. The server uses standard input/output (STDIO) for communication, which is perfect for Claude Desktop integration. You can stop the server with Ctrl+C.

How to Configure Claude Desktop

Now that your server runs properly, configure Claude Desktop to connect to it. The configuration file location depends on your operating system:

For macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

For Windows:

%APPDATA%\Claude\claude_desktop_config.json

For Linux:

~/.config/Claude/claude_desktop_config.json

Create or edit this file with your exact paths. Your configuration should look like this:

{
  "mcpServers": {
    "example-mcp": {
      "command": "/Users/yourusername/path/to/mcp-server/venv/bin/python",
      "args": ["/Users/yourusername/path/to/mcp-server/server.py"],
      "cwd": "/Users/yourusername/path/to/mcp-server"
    }
  }
}

Replace /Users/yourusername/path/to/mcp-server/ with your actual path. You can get your precise path by running pwd in your MCP server directory.

The configuration tells Claude Desktop:

Which Python interpreter to use (from your virtual environment)
Where to find the server script
Which directory to run the server from

How to Restart Claude Desktop and Test Integration

After saving your configuration file, altogether quit Claude Desktop (not just close the window). On macOS, use Cmd+Q or right-click the dock icon and select Quit. Then restart Claude Desktop.

Once Claude Desktop is running again, test your MCP integration. You can verify the connection by:

Looking for your MCP server name in Claude's interface
Testing basic MCP functionality with prompts like:
- "What MCP tools are available?"
- "Can you check the MCP server status?"
- "Show me the available MCP commands"

If everything is working correctly, Claude will respond using the MCP server tools, confirming successful integration.

Understanding MCP Server Capabilities

MCP servers extend Claude's capabilities by providing structured access to external tools and data sources. Common MCP server implementations include:

File system operations: MCP servers can provide controlled access to local files, allowing Claude to read, analyze, and process documents while maintaining security boundaries.
API integrations: Connect Claude to external services through MCP servers that handle authentication, rate limiting, and data formatting for various APIs.
Database connections: Query databases safely through MCP servers that manage connections, handle credentials securely, and format results for Claude's consumption.
Custom tools: Build specialized tools for your workflow, from code analysis to data processing, all accessible through the standardized MCP interface.

The beauty of MCP is its flexibility – you can create servers for virtually any tool or service you need Claude to interact with.

Alternative Installation Methods

If you want more streamlined approaches for future setups, here are two excellent alternatives:

Method 1: Direct Package Installation

For MCP servers available as packages, you can install directly:

pip install mcp-server-package

Then use this simpler configuration:

{
  "mcpServers": {
    "example-mcp": {
      "command": "mcp-server-command"
    }
  }
}

This method works when the MCP server provides a command-line entry point through its setup configuration.

Method 2: Using UV Package Manager

UV provides more robust dependency management – perfect if you're tired of Python version conflicts:

# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Use UV in your configuration
{
  "mcpServers": {
    "example-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "python",
        "/path/to/mcp-server/server.py"
      ],
      "cwd": "/path/to/mcp-server"
    }
  }
}

UV automatically manages Python versions and dependencies, reducing the likelihood of environment-related errors.

How to Prevent Future ENOENT Errors

To avoid this issue in the future, follow these best practices:

1. Use Virtual Environment Copies Instead of Symlinks

When creating virtual environments, use the --copies flag:

python3 -m venv venv --copies

This creates actual copies of files instead of symlinks, making your environment more resilient to Python upgrades.

2. Pin Your Homebrew Python Version

Prevent automatic Python upgrades that break environments:

brew pin python@3.11

Remember to unpin when you're ready to upgrade intentionally.

3. Create a Health Check Script

Save this script as health_check.sh in your MCP server directory:

#!/bin/bash
# health_check.sh
echo "Checking Python virtual environment..."
source venv/bin/activate

python -c "import sys; print(f'Python: {sys.executable}')"
python -c "print('✓ Python is working')"

# Check for common MCP dependencies
python -c "import json; print('✓ JSON module available')"
python -c "import asyncio; print('✓ Asyncio available')"

echo "Health check complete!"

Make it executable and run it periodically:

chmod +x health_check.sh
./health_check.sh

4. Document Your Python Version

Create a .python-version file in your project:

python --version > .python-version

This helps you remember which Python version the project was built with.

Troubleshooting Common Issues

Even with the fix applied, you might encounter these challenges:

Import Errors

If you see import-related errors, ensure all dependencies are installed:

source venv/bin/activate
pip list  # Check installed packages
pip install -r requirements.txt  # Reinstall if needed

Permission Denied Errors

Make sure your server file is executable:

chmod +x server.py

Claude Desktop Not Finding the Server

Double-check your configuration paths are absolute, not relative:

# Good - absolute path
"/Users/username/projects/mcp-server/server.py"

# Bad - relative path
"./server.py"

Server Starts, But Claude Can't Connect

Verify that the transport method matches between your server and the configuration. Most MCP servers use STDIO, but some might use HTTP or WebSocket transports.

Multiple Python Installations

If you have multiple Python versions, be explicit about which one to use:

# Check available Python versions
ls -la /usr/local/bin/python*

# Use a specific version
/usr/local/bin/python3.11 -m venv venv

Conclusion

You've successfully fixed the "spawn python ENOENT" error by rebuilding your Python virtual environment and properly configuring your MCP server for Claude Desktop. You've also learned how to prevent future mistakes and troubleshoot common issues.

With your MCP server running smoothly, you can now:

Build custom tools that extend Claude's capabilities
Create integrations with your favorite services
Develop specialized workflows for your specific needs
Share your MCP servers with the community

The MCP ecosystem is growing rapidly, with new servers and tools being developed constantly. Whether you're building file system tools, API integrations, or custom utilities, you now have the foundation to create and maintain robust MCP servers.

Happy building, and enjoy your error-free development journey! For more tutorials, follow my work on GitHub.

mcp server - freeCodeCamp.org

How to Create a Marketing Landing Page Using shadcn/ui

Table of Contents

Prerequisites

What Are We Building?

Why Build with Shadcn Space?

Sections We'll Build

Final Page Structure

Project Setup with Base UI Using the Shadcn Preset

1. Create the Project with Base UI

2. Add the Shadcn Space Registry

Two Ways to Build Your Marketing Landing Page

Option 1: Build Using the CLI

Step 1: Browse Marketing Blocks

Step 2: Install Selected Blocks

Step 3: Add a Hero Section

1. Install the Hero Block

3. Render the Hero Section

Install the Remaining Blocks

Customize the Marketing Landing Page

Option 2: Build Using the MCP Server

Step 1: Install the MCP Server

Step 2: Open the AI Chat

Step 3: Generate the Landing Page

How to Optimize Your Landing Page

Optimize Images with Next.js

Improve SEO for Your Landing Page

Add Metadata and Open Graph Images

Optimize Performance

Improve Core Web Vitals

How to Expand Your Marketing Website

Live Preview:

Conclusion

How to Build Your Own MCP Server and Publish Your ChatGPT App with Supabase Auth and DigitalOcean

What We'll Cover:

What is an MCP Server?

What Can You Do with an MCP Server?

Level 1: How to Build Your Own MCP Server

Step 0: Prepare your project

Step 1: Create a Node.js Server

Step 2: Setting Up MCP Server SDK

Step 3: Add MCP Server Tools – Create and Add a Todo

Step 4: List Todos from MCP Server

Step 5: Add Todo Complete Functions

Step 6: Connect Your MCP Server with the Node.js Server

How to Test Your MCP Server

Level 2: How to Build the UI

Step 1: Create the HTML File to Show the UI

Todo list

Step 2: Add a JavaScript Module to Handle MCP Server Data.

Step 3: Styling your UI

Step 4: Add the UI to your MCP Server:

Step 5: Update Your MCP Server to Handle the UI

How to Test Your ChatGPT App

Level 3: How to Add Supabase (Auth and Database) to the MCP Server

Step 1: Create the Todos Table

Step 2: Enabling the MCP Server to Connect with Supabase Auth

Step 3: Create a Proxy Server for the MCP Server to Handle the Auth.

Step 4: Implementing the Consent and Login Page

Authentication

Authorization Required

Step 5: Testing the OAuth Implementation with MCP Server Inspector

Step 6: Adding OAuth Security to Your MCP Server Tools

Step 7: Updating the MCP Server Function to Handle the Authentication

Step 8: Testing the Server with Supabase:

How to Deploy your MCP Server to DigitalOcean

How to Publish Your ChatGPT App

What to Do Next

Acknowledgments:

References:

How to Build an Agentic Terminal Workflow with GitHub Copilot CLI and MCP Servers

Table of Contents

Prerequisites

What is GitHub Copilot CLI?

What is the Model Context Protocol?

How MCP Servers Work in a Terminal Context

Step 1 – Install and Configure GitHub Copilot CLI

Step 2 – Set Up Your First MCP Server

Step 3 – Wire Copilot CLI to Your MCP Server

Step 4 – Build a Real Agentic Workflow

What Is the `dart_mcp` Package?