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.

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

• 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:

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:

1. Start the mcp-server-git process

2. Call git_log to retrieve recent commits

3. Call git_diff on the most recent commit

4. 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:

1. Call docker_logs (server-docker) to pull the container's recent stderr output

2. Call read_file (server-filesystem) to read your Dockerfile

3. Parse the HEALTHCHECK instruction

4. Cross-reference the log errors with the health endpoint path

5. 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:

1. Only declare the servers you actually need for a given project in your mcp.json

2. 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.

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.

Table of Contents

• What You Will Build

• Prerequisites

• What is MCP (and Why Should You Care)?

• Why Claude Code Instead of Claude Desktop?

• Step 1: Build the MCP Server

• Step 2: Test It Locally

• Step 3: Dockerize It

• Step 4: Wire It Into Claude Code

• Step 5: Use It

• Security: What the Other Tutorials Leave Out

• What to Do Next

• Wrapping Up

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:

1. 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.

2. 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.

3. 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.

4. 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 <name> -- <command>

# List configured servers
claude mcp list

# Remove a server
claude mcp remove <name>

# 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:

1. 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.

2. 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:

1. 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.

2. 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.

3. 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.

4. 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.

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.

Table of Contents

• Prerequisites

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

• Architecture Overview

• Setting Up the Project

• Building the MCP Server

  • Step 1: Server Skeleton

  • Step 2: Connecting to Internal Data

  • Step 3: Defining Tools

  • Tool Design Principles

  • Step 4: Exposing Resources

  • Step 5: Transport and Startup

• 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

  • Dockerizing the MCP Server

  • Health Checks and Monitoring

  • Logging and Audit Trail

• 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<Employee[]> {
  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<Employee>(
    `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<Project[]> {
  const result = await pool.query<Project>(
    `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<Employee[]> {
  const result = await pool.query<Employee>(
    `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<string, StreamableHTTPServerTransport>();

// 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 <token> 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<void> {
    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<string> {
    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<OAuthTokens> {
    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<OAuthTokens>;
  }

  // Refresh expired tokens
  async exchangeRefreshToken(
    client: OAuthClientInformationFull,
    refreshToken: string
  ): Promise<OAuthTokens> {
    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<OAuthTokens>;
  }

  // Validate an access token on every request
  async verifyAccessToken(token: string): Promise<AuthInfo> {
    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:

1. Extract user context from the authenticated session

2. Filter queries at the database level (not after fetching everything)

3. Redact fields the user shouldn't see

4. 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<string, unknown>;
      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<T extends Record<string, unknown>>(
  handler: (params: T) => Promise<ToolResult>,
  toolName: string,
  audit: ReturnType<typeof createAuditLogger>
) {
  return async (params: T): Promise<ToolResult> => {
    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<string, number[]>();

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:

1. Good tool design — clear descriptions, typed parameters, structured responses

2. Proper access control — authenticate users, scope data access, log everything

3. 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.

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.

Table of Contents:

1. Prerequisites

2. What is MCP (Model Context Protocol)?

3. Why MCP Matters for Dart and Flutter Developers

4. MCP in the Dart Ecosystem

   • What Is the dart_mcp Package?

5. Real-world use cases

6. How MCP actually works

7. Getting started, step-by-step

   • 1) Prerequisites

   • 2) Start the Dart & Flutter MCP server locally

   • 3) Configure an MCP client

   • 4) Try an easy request from your IDE assistant

   • 5) Build a custom capability (optional)

8. Hands-on example

   • Step-by-step explanation

9. How to Build a Simple MCP Server in Dart

   • Step 1: Add Dependency

   • Step 2: Create the Server

10. Example: Creating an MCP Client

11. MCP vs. Custom HTTP Servers

12. Best Practices, Safety, and Permissions

13. Getting Started as a Beginner

14. Moving Beyond Beginner Level

15. Conclusion

16. References

Prerequisites

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

1. Dart SDK 3.9 or later/Flutter 3.35 beta or later installed on your machine.

2. Basic understanding of async programming in Dart (using async / await).

3. Familiarity with standard I/O streams (stdin, stdout) since the MCP client communicates through them.

4. Access to an MCP-compatible server (for example, Dart MCP Server or a custom implementation).

5. 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:

1. 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.

2. You can extend your development workflow, letting AI assistants interact directly with your local Dart projects, run commands, analyze files, or trigger Flutter builds.

3. 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:

1. Build MCP servers that expose tools and capabilities.

2. Build MCP clients that connect to those servers.

3. Support for STDIO transport, allowing local, low-latency communication.

4. Support for Prompts, Resources, and Tools capabilities.

5. Protocol-aligned structure for initialization, schema validation, and request/response handling.

Limitations (as of version 0.3.3):

1. HTTP and streamable transports are still experimental.

2. Authorization and batching aren’t fully supported yet.

3. 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:

1. Fix a runtime UI bug. The AI inspects runtime logs and the widget tree, then suggests and applies a fix for a RenderFlex overflow.

2. 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.

3. Automated code review. On each PR, an AI agent runs dart analyze and flutter test, and comments with suggested improvements.

4. Learning and mentorship. The tool can inspect a learner’s project and then suggest idiomatic Flutter patterns and add unit tests.

5. 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:

1. Save the file in the root of a Dart project.

2. Run dart run simple_mcp_server.dart.

3. 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:

1. Read about MCP basics: Visit the official Dart MCP page to understand what it is and where it fits in your workflow.

2. Install and explore dart_mcp: Try running one of the examples on pub.dev. Experiment with building your own simple tool.

3. 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.

4. Expand your tools: Build more complex commands like “run tests,” “format code,” “fetch dependencies,” or “generate reports.”

5. 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

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

  • 1. Connect your Neon Database

  • 2. Create your DB File

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

  • 4. Full setup-db.ts File

• Authentication with Kinde

  • 1. Create a Kinde Application

  • 2. Configure Kinde Settings

  • 3. Environment Variables

  • 4. Create the Kinde Auth Server

  • 5. Complete Authentication Flow

  • 6. Why This Matters

  • 7. Key Connections

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

• MCP Server Implementation (with Billing System Integration)

  • 1. Create Your File

  • 2. Project Setup and Imports

  • 3. Database Connection and Configuration

  • 4. Authentication System

  • 5. Core Helper Functions

  • 6. Core Server Implementation

  • 7. Register Tools

  • 8. Tool Handlers

  • 9. Full server.ts File

  • 10. Data Flow & Integration

  • 11. Error Handling & Security

  • 12. Testing & Deployment

• Testing the Complete System

  • 1. Start the Services

  • 2. Configure Cursor MCP

  • 3. Test the Complete Flow

• Troubleshooting

  • 1. MCP Server Not Detected

  • 2. Database Connection Issues

  • 3. Kinde Authentication Problems

  • 4. Token Errors

• 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: '<http://localhost:3000/callback>',
  logoutRedirectURL: '<http://localhost:3000>',
});

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 <https://learnflowai.kinde.com/portal> 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: <http://localhost:3000>
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 <http://localhost:3000>\\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:** <https://learnflowai.kinde.com/portal`>,
        },
      ],
    ];
  }

  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: '<https://learnflowai.kinde.com/portal>',
            selfServicePortal: '<https://learnflowai.kinde.com/portal>',
            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: <your-jwt-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": "<https://your-domain.kinde.com>",
        "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.

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.

Table of Contents

1. What Causes the ENOENT Error?

2. Prerequisites

3. How to Diagnose Your Broken Virtual Environment

4. How to Completely Rebuild Your Virtual Environment

5. How to Install MCP Server Dependencies

6. How to Locate Your Server Files

7. How to Test Your Server Setup

8. How to Configure Claude Desktop

9. How to Restart Claude Desktop and Test Integration

10. Understanding MCP Server Capabilities

11. Alternative Installation Methods

    • Method 1: Direct Package Installation

    • Method 2: Using UV Package Manager

12. How to Prevent Future ENOENT Errors

13. Troubleshooting Common Issues

14. 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:

1. Looking for your MCP server name in Claude's interface

2. 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:

1. File system operations: MCP servers can provide controlled access to local files, allowing Claude to read, analyze, and process documents while maintaining security boundaries.

2. API integrations: Connect Claude to external services through MCP servers that handle authentication, rate limiting, and data formatting for various APIs.

3. Database connections: Query databases safely through MCP servers that manage connections, handle credentials securely, and format results for Claude's consumption.

4. 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.