An AI assistant can help with that workflow, but only if it can query a real catalog and persist what you already decided. Chat history isn't a database. A hallucinated deadline is worse than no deadline at all.

The Model Context Protocol (MCP) is the standard way to give AI apps that kind of access. In this tutorial, you'll build a scholarship research MCP server with Node.js, Express, and MongoDB.

When you finish, Cursor, Claude Desktop, or any other MCP host will be able to search awards, match them to a student profile, bookmark a shortlist, and store research notes. The model stays the reasoning layer while your server owns the data.

You'll build:

• A MongoDB catalog of scholarships, plus saved-list and notes collections

• Nine MCP tools for search, matching, deadlines, comparison, and research tracking

• Resources so a client can read the catalog without calling a tool

• Prompts that turn a student profile into a research plan

• An Express app that serves MCP over Streamable HTTP

The sample catalog in this project is a teaching dataset. Amounts, dates, and eligibility rules are simplified. Always confirm details on the official application page before applying.

What You Need

You should be comfortable with JavaScript and basic Express routing. You don't need prior MCP experience.

Install:

• Node.js 20 or later

• MongoDB running locally, or a free MongoDB Atlas cluster

• An MCP client if you want to try the last section. Cursor and Claude Desktop both work.

Docker is enough for MongoDB:

docker run -d --name mongo -p 27017:27017 mongo:7

Table of Contents

• What You Need

• What Is the Model Context Protocol?

• Why a Scholarship Research Server?

• How the Architecture Fits Together

• How to Set Up the Project

• How to Connect MongoDB

• How to Model Scholarship Data

• How to Write the Scholarship Service

• How to Register MCP Tools

• How to Expose Resources and Prompts

• How to Serve MCP Over Express

• How to Seed the Catalog

• How to Test the Server

• How to Connect Cursor and Claude Desktop

• How a Research Session Runs

• How the Matching Logic Works

• What You Can Build Next

• Conclusion

What Is the Model Context Protocol?

MCP is an open protocol that lets an AI application talk to external tools and data sources through a shared contract. Anthropic introduced it in 2024, and it's now maintained as an open standard.

Anthropic described MCP as "a USB-C port for AI applications": one connector, many hosts. (Source: Introducing the Model Context Protocol) Instead of writing one integration for Cursor, another for Claude Desktop, and a third for a custom agent, you implement the protocol once.

The official architecture overview splits MCP into two layers:

• The data layer is JSON-RPC 2.0. Clients and servers exchange requests such as tools/list and tools/call.

• The transport layer moves those messages. Local servers usually use stdio. Remote or long-running servers use Streamable HTTP.

This tutorial uses Streamable HTTP, because Express is already an HTTP server and you want the catalog available to any client on your machine.

Hosts, Clients, and Servers

Three roles show up in every MCP setup:

• The host is the AI app. Cursor and Claude Desktop are hosts.

• The client lives inside the host. The host creates one client per connected server.

• The server is your program. It advertises tools, resources, and prompts, then handles calls.

Your scholarship app is the server. You never talk to the model SDK directly. The host does that.

Tools, Resources, and Prompts

MCP servers expose three primitives. You'll use all three.

Tools are actions. The model decides to call them, the way it might call a function in a regular tool-calling API. Search, save, and compare belong here.

Resources are data the host can read and attach as context. A catalog URI and a per-scholarship URI belong here. The model doesn't have to "take an action" to see them.

Prompts are named templates. People usually invoke them from a slash command or a menu. A "research plan" prompt belongs here, because it's a workflow you want to start on purpose.

That split matters. If you put everything in tools, the model has to guess when to look things up. Resources and prompts give the host better knobs.

Why a Scholarship Research Server?

A weather MCP demo is a single API call. Scholarship research is closer to a real product:

• The catalog must be queryable. Keyword search, GPA filters, and deadline windows all live in the database.

• The workflow must persist. A saved shortlist and research notes should survive a new chat.

• Eligibility is logic, not prose. A GPA minimum is a number. First-generation-only is a boolean. Put those checks in code so the model can't invent a match.

• The output must be inspectable. Students should be able to open the official URL and verify every claim.

MongoDB fits this well. Each scholarship is a document with nested arrays for fields of study, citizenship, and requirements. Saved items and notes are separate collections with references back to the catalog.

You could wrap a public API instead of storing documents. That's a good follow-up. Starting with your own catalog keeps the tutorial self-contained and makes the MCP contract obvious.

How the Architecture Fits Together

The finished project looks like this:

MCP host (Cursor or Claude Desktop)
        |
        |  Streamable HTTP  POST /mcp
        v
Express app  (createMcpExpressApp)
        |
        |  createMcpHandler factory
        v
McpServer  tools / resources / prompts
        |
        v
Scholarship service
        |
        v
MongoDB  scholarships, savedScholarships, researchnotes

A few design choices are worth calling out before you write code.

The MCP handler is stateless. The SDK runs your server factory once per HTTP request. That's the recommended v2 pattern for Streamable HTTP. Don't keep tool state on the McpServer instance. Keep it in MongoDB.

The database connection is process-wide. Connecting on every request would be slow and pointless. You connect once at startup and close over that pool from the tools.

The HTTP surface is small on purpose. /health is for you. /mcp is for the protocol. You don't need a REST API in front of the same data unless you want one later.

How to Set Up the Project

Create a folder and initialize a Node.js project. ESM is required because the MCP SDK is ESM-first.

mkdir scholarship-research-mcp-server
cd scholarship-research-mcp-server
npm init -y

Open package.json and set "type": "module". Then install the SDK, Express, Mongoose, Zod, and dotenv:

npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express mongoose dotenv zod

The SDK split into packages in v2:

• @modelcontextprotocol/server is the McpServer class and createMcpHandler

• @modelcontextprotocol/express gives you createMcpExpressApp, including DNS rebinding protection

• @modelcontextprotocol/node adapts the web-standard handler to Node's req/res

Create a .env file:

MONGODB_URI=mongodb://127.0.0.1:27017/scholarship_research
PORT=3000
HOST=127.0.0.1

Add a .gitignore that excludes node_modules and .env.

Your source layout can stay small:

src/
  index.js
  config.js
  db.js
  models/
  services/
  mcp/
  utils/
data/
  scholarships.json
scripts/
  seed.js
  smoke-test.js

src/config.js reads environment variables with defaults:

export const config = {
  mongodbUri: process.env.MONGODB_URI ?? "mongodb://127.0.0.1:27017/scholarship_research",
  port: Number(process.env.PORT ?? 3000),
  host: process.env.HOST ?? "127.0.0.1",
};

Keep configuration in one file. Tools shouldn't read process.env directly.

How to Connect MongoDB

Mongoose 9 works cleanly with ESM. A short src/db.js is enough:

import mongoose from "mongoose";
import { config } from "./config.js";

export async function connectDatabase() {
  mongoose.set("strictQuery", true);
  await mongoose.connect(config.mongodbUri);
  return mongoose.connection;
}

Call this once in src/index.js before app.listen. If the connection fails, the process should exit. A running Express server with a dead database is harder to debug than a failed startup.

How to Model Scholarship Data

You need three collections.

Scholarship

This is the catalog. Store the fields a matching engine actually uses, not a blob of markdown.

import mongoose from "mongoose";

const scholarshipSchema = new mongoose.Schema(
  {
    title: { type: String, required: true, trim: true },
    provider: { type: String, required: true, trim: true },
    description: { type: String, required: true },
    amountMin: { type: Number, default: 0 },
    amountMax: { type: Number, default: 0 },
    currency: { type: String, default: "USD" },
    deadline: { type: Date, default: null },
    rolling: { type: Boolean, default: false },
    educationLevels: { type: [String], default: ["undergraduate"] },
    fieldsOfStudy: { type: [String], default: ["any"] },
    gpaMinimum: { type: Number, default: null },
    citizenship: { type: [String], default: ["any"] },
    countries: { type: [String], default: ["any"] },
    firstGenerationOnly: { type: Boolean, default: false },
    womenOnly: { type: Boolean, default: false },
    numberOfAwards: { type: Number, default: 1 },
    renewable: { type: Boolean, default: false },
    applicationUrl: { type: String, required: true },
    applicationRequirements: { type: [String], default: [] },
  },
  { timestamps: true },
);

scholarshipSchema.index({
  title: "text",
  provider: "text",
  description: "text",
  fieldsOfStudy: "text",
});
scholarshipSchema.index({ deadline: 1 });
scholarshipSchema.index({ amountMax: -1 });

export const Scholarship = mongoose.model("Scholarship", scholarshipSchema);

A few field choices are doing real work:

• fieldsOfStudy: ["any"] means the award is field-open. The matcher treats any as a wildcard.

• deadline: null plus rolling: true covers programs that accept applications year-round.

• applicationUrl is mandatory. Every tool result should point back to a human-verifiable source.

• gpaMinimum: null means the provider didn't publish a cutoff. That's different from 0.

Saved Scholarship

A research list is a join between a person and a catalog row.

const savedScholarshipSchema = new mongoose.Schema(
  {
    researcherId: { type: String, required: true, default: "default" },
    scholarship: {
      type: mongoose.Schema.Types.ObjectId,
      ref: "Scholarship",
      required: true,
    },
    status: {
      type: String,
      enum: ["saved", "applying", "submitted", "won", "rejected"],
      default: "saved",
    },
  },
  { timestamps: true },
);

savedScholarshipSchema.index({ researcherId: 1, scholarship: 1 }, { unique: true });

The unique index makes save_scholarship idempotent. Saving the same award twice updates the status instead of creating duplicates.

researcherId is a plain string. For a tutorial, that's enough. In production you would take it from an auth token.

Research Note

Notes are a separate collection so one scholarship can have many of them.

const researchNoteSchema = new mongoose.Schema(
  {
    researcherId: { type: String, required: true, default: "default" },
    scholarship: {
      type: mongoose.Schema.Types.ObjectId,
      ref: "Scholarship",
      required: true,
    },
    body: { type: String, required: true, trim: true },
  },
  { timestamps: true },
);

You now have a catalog, a shortlist, and a notebook. That's the whole product surface the MCP tools will wrap.

How to Write the Scholarship Service

Keep MongoDB queries out of the MCP layer. Tools should call a service, get plain objects back, and format text. That makes the same functions reusable from a seed script, a smoke test, or a future REST route.

Search

Search is a filter builder. Each optional argument adds a clause. Open or rolling awards stay in the result set. Closed deadlines drop out.

const OPEN_DEADLINE_FILTER = {
  $or: [{ rolling: true }, { deadline: null }, { deadline: { $gte: new Date() } }],
};

export async function searchScholarships(filters) {
  const query = { ...OPEN_DEADLINE_FILTER };
  const and = [query];

  if (filters.keyword) {
    and.push({
      $or: [
        { title: { $regex: escapeRegex(filters.keyword), $options: "i" } },
        { provider: { $regex: escapeRegex(filters.keyword), $options: "i" } },
        { description: { $regex: escapeRegex(filters.keyword), $options: "i" } },
        { fieldsOfStudy: { $regex: escapeRegex(filters.keyword), $options: "i" } },
      ],
    });
  }

  if (filters.fieldOfStudy) {
    and.push({
      $or: [
        { fieldsOfStudy: { $regex: `^any$`, $options: "i" } },
        { fieldsOfStudy: { $regex: escapeRegex(filters.fieldOfStudy), $options: "i" } },
      ],
    });
  }

  // educationLevel, citizenship, country, minAmount, gpa, flags...

  const results = await Scholarship.find({ $and: and })
    .sort({ deadline: 1, amountMax: -1 })
    .limit(100)
    .lean();

  return rankByFieldMatch(results, filters.fieldOfStudy).slice(0, filters.limit ?? 10);
}

Two details are easy to skip and worth keeping.

Escape user input before you drop it into $regex. A keyword of ( shouldn't become a broken regular expression.

When a student searches for computer science, field-open awards (any) are eligible, but the specific CS scholarships should appear first. Rank in memory after the query. MongoDB already did the eligibility filter. You're only adjusting display order.

Match

Matching is not the same as search. Search is "find documents that look like this." Matching is "here is a student, score every open award."

The service loads open scholarships, then applies hard filters and a score:

Hard filters prevent false hope. Soft scores rank the rest. Each result also returns a reasons array, so the model can explain the match instead of inventing one.

That last point is the whole reason to put matching on the server. If you only return raw documents, the model will sometimes "helpfully" include an award the student can't apply for. Returning score and reasons keeps the explanation grounded in code.

Save, Notes, Deadlines, Compare

The remaining functions are thin:

• saveScholarship upserts by (researcherId, scholarshipId)

• addResearchNote inserts a note after confirming the scholarship exists

• getUpcomingDeadlines queries deadline between now and now + N days

• compareScholarships loads two or three documents and returns the same fields for each

Validate MongoDB ids with mongoose.Types.ObjectId.isValid before you query. An LLM will occasionally pass a title where you asked for an id. Fail clearly. Don't throw a CastError into the MCP transport.

How to Register MCP Tools

Create src/mcp/server.js as a factory. The HTTP handler will call it on every request.

import { McpServer } from "@modelcontextprotocol/server";
import { registerPrompts } from "./prompts.js";
import { registerResources } from "./resources.js";
import { registerTools } from "./tools.js";

export function createScholarshipServer() {
  const server = new McpServer({
    name: "scholarship-research",
    version: "1.0.0",
  });

  registerTools(server);
  registerResources(server);
  registerPrompts(server);

  return server;
}

Keep this factory cheap. No database connections, no file reads, and no caches that belong at module scope. The HTTP serving guide is explicit about this: create connection pools once at startup, and close over them.

One Tool, Fully

registerTool takes a name, a config object, and a handler. The inputSchema is a Zod object. The SDK turns that schema into JSON Schema for tools/list, validates arguments before your handler runs, and infers types if you're on TypeScript.

import * as z from "zod/v4";

server.registerTool(
  "search_scholarships",
  {
    title: "Search scholarships",
    description:
      "Search the scholarship catalog by keyword, field of study, education level, citizenship, country, GPA, and award amount.",
    inputSchema: z.object({
      keyword: z.string().min(1).optional().describe("Free-text search across title, provider, description, and fields"),
      fieldOfStudy: z.string().optional().describe("For example computer science, public health, or engineering"),
      educationLevel: z.enum(["undergraduate", "graduate", "doctoral"]).optional(),
      citizenship: z.string().optional(),
      country: z.string().optional(),
      minAmount: z.number().nonnegative().optional(),
      gpa: z.number().min(0).max(4).optional(),
      firstGeneration: z.boolean().optional(),
      womenOnly: z.boolean().optional(),
      limit: z.number().int().min(1).max(25).optional(),
    }),
    annotations: { readOnlyHint: true, openWorldHint: false },
  },
  async (args) => {
    const results = await searchScholarships(args);
    return toolText(formatScholarshipList(results));
  },
);

Write descriptions as if the model is the only docs the tool will ever get. .describe() on a Zod field survives conversion to JSON Schema. That's how the host tells the model what fieldOfStudy means.

title is the human label. description is the model-facing contract. They're not the same string.

Annotations

Annotations don't change how the SDK runs the tool. Hosts use them to decide how cautious to be.

• readOnlyHint: true for search, get, match, list, compare, and deadlines

• readOnlyHint: false for save and add-note

• idempotentHint: true on save, because of the unique index

• openWorldHint: false because this server talks to your database, not the open web

A host can auto-approve a read-only search and ask the user before a write. That's worth five extra keys in the config.

Return Shape

Every tool returns MCP content blocks:

export function toolText(text, isError = false) {
  return {
    content: [{ type: "text", text }],
    isError,
  };
}

Return isError: true for domain failures such as "scholarship not found." Throw only for unexpected failures. The spec treats those differently. A validation error from Zod never reaches your handler. The SDK already converts it into an isError result.

Format lists for a person who is skimming a chat transcript. Include the MongoDB id on every row. Later tools need that id, and the model can't invent a valid ObjectId.

The Full Tool Set

The server registers nine tools:

That's enough for a research loop: find, inspect, match, save, annotate, and compare.

Resist the urge to add a delete_everything tool. Destructive tools need extra confirmation and aren't part of this workflow.

How to Expose Resources and Prompts

Tools aren't the only way a host gets context.

Resources

A static resource is a fixed URI. The catalog fits that:

server.registerResource(
  "scholarship-catalog",
  "scholarship://catalog",
  {
    title: "Scholarship catalog",
    description: "Open scholarships currently stored in MongoDB",
    mimeType: "application/json",
  },
  async (uri) => {
    const catalog = await listCatalog();
    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(catalog, null, 2),
        },
      ],
    };
  },
);

A resource template covers a family of URIs. Use scholarship://item/{id} rather than scholarship://{id}. If the pattern is scholarship://{id}, the URI scholarship://catalog becomes ambiguous.

import { ResourceTemplate } from "@modelcontextprotocol/server";

server.registerResource(
  "scholarship-record",
  new ResourceTemplate("scholarship://item/{id}", {
    list: async () => {
      const catalog = await listCatalog(20);
      return {
        resources: catalog.map((scholarship) => ({
          uri: `scholarship://item/${scholarship._id}`,
          name: scholarship.title,
          mimeType: "text/plain",
        })),
      };
    },
  }),
  {
    title: "Scholarship record",
    description: "Full details for one scholarship",
    mimeType: "text/plain",
  },
  async (uri, { id }) => {
    const scholarship = await getScholarshipById(id);
    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "text/plain",
          text: scholarship
            ? formatScholarship(scholarship)
            : `No scholarship found with id ${id}.`,
        },
      ],
    };
  },
);

list is required on a template. Pass undefined if you can't enumerate instances. Here you can, so the host can show a picker.

Prompts

Prompts are workflows you want a person to start. The research plan prompt doesn't query MongoDB itself. It tells the model to use the tools, then structure the answer.

server.registerPrompt(
  "research-plan",
  {
    title: "Scholarship research plan",
    description: "Build a week-by-week research and application plan from a student profile.",
    argsSchema: z.object({
      fieldOfStudy: z.string(),
      educationLevel: z.string(),
      citizenship: z.string(),
      gpa: z.string(),
      weeks: z.string().optional(),
    }),
  },
  ({ fieldOfStudy, educationLevel, citizenship, gpa, weeks }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Create a ${weeks || "6"}-week scholarship research plan for this student.

Field of study: ${fieldOfStudy}
Education level: ${educationLevel}
Citizenship: ${citizenship}
GPA: ${gpa}

Use the scholarship research tools to find real awards first. Then produce a shortlist, a week-by-week plan, and risks. Name actual scholarships and dates from the tool results.`,
        },
      },
    ],
  }),
);

Notice the instruction "use the scholarship research tools." A prompt isn't a substitute for tools. It's a script that makes tool use more likely and the output shape more consistent.

A second prompt, application-checklist, takes a scholarship id and asks for a document list and a backward calendar. That's the kind of repetitive work MCP prompts are good at.

Prompt arguments are strings in many hosts, even when the value is a number. Typing gpa as a string avoids a frustrating expected number, received string error from a slash-command form.

How to Serve MCP Over Express

This is the part that used to be a page of session-handling code. In SDK v2 it's a factory plus one route.

import "dotenv/config";
import { createMcpExpressApp } from "@modelcontextprotocol/express";
import { toNodeHandler } from "@modelcontextprotocol/node";
import { createMcpHandler } from "@modelcontextprotocol/server";
import { config } from "./config.js";
import { connectDatabase } from "./db.js";
import { createScholarshipServer } from "./mcp/server.js";

const mcpHandler = createMcpHandler(() => createScholarshipServer());
const nodeHandler = toNodeHandler(mcpHandler);

const app = createMcpExpressApp({
  host: config.host,
  allowedHosts: ["127.0.0.1", "localhost"],
});

app.get("/health", (_req, res) => {
  res.json({
    status: "ok",
    service: "scholarship-research-mcp",
    transport: "streamable-http",
  });
});

app.all("/mcp", (req, res) => {
  void nodeHandler(req, res, req.body);
});

async function start() {
  await connectDatabase();
  app.listen(config.port, config.host, () => {
    console.log(`Scholarship research MCP server listening on http://${config.host}:${config.port}/mcp`);
  });
}

start();

Walk through what each helper is doing.

createMcpHandler takes a function that returns a fresh McpServer. It exposes a web-standard fetch. That's the same handler you would export from a Cloudflare Worker.

toNodeHandler adapts that fetch to Express (req, res). You pass req.body as the third argument because createMcpExpressApp already ran express.json(). If you omit the body, the adapter tries to read a stream Express already consumed.

createMcpExpressApp is express() with two extras: JSON parsing, and Host/Origin checks. Those checks exist because of DNS rebinding. A malicious page can point its own domain at 127.0.0.1 and, without a Host check, your browser would treat the local MCP server as same-origin. The default bind is 127.0.0.1 for that reason. The Express serving guide covers this in more detail.

app.all("/mcp", ...) is intentional. Streamable HTTP uses POST for JSON-RPC, and GET for SSE streams. Registering only POST will break some clients.

Shut the handler down on SIGINT:

process.on("SIGINT", async () => {
  await mcpHandler.close();
  process.exit(0);
});

close() waits for in-flight requests. Then you can exit.

Add npm scripts:

{
  "scripts": {
    "start": "node src/index.js",
    "dev": "node --watch src/index.js",
    "seed": "node scripts/seed.js",
    "smoke": "node scripts/smoke-test.js"
  }
}

node --watch is enough for local development. You don't need nodemon for this project.

How to Seed the Catalog

MCP tools against an empty database will work and return "no scholarships matched." That's correct, and also a bad first impression.

Put 20 to 30 realistic records in data/scholarships.json. Mix:

• Undergraduate and graduate awards

• STEM and field-open awards

• Country-specific programs and global ones

• Rolling deadlines and hard dates

• First-generation and women-only flags

A seed script should replace the catalog, not append:

import "dotenv/config";
import { readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { connectDatabase } from "../src/db.js";
import { Scholarship } from "../src/models/index.js";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

async function seed() {
  await connectDatabase();
  const raw = await readFile(path.join(__dirname, "..", "data", "scholarships.json"), "utf8");
  await Scholarship.deleteMany({});
  const inserted = await Scholarship.insertMany(JSON.parse(raw));
  console.log(`Seeded ${inserted.length} scholarships.`);
  process.exit(0);
}

seed();

Run it:

npm run seed

Treat the JSON as sample data. Names of well-known programs help the tutorial feel real. They also create a duty to say, clearly, that students must verify every number and date on the official site. The applicationUrl field exists so that reminder has somewhere to point.

If you later replace the JSON with a live source, keep the same schema. The MCP tools shouldn't care where the documents came from.

How to Test the Server

Start MongoDB, seed, then start the process:

npm run seed
npm start

You should see:

Scholarship research MCP server listening on http://127.0.0.1:3000/mcp

Health Check

curl -s http://127.0.0.1:3000/health

A JSON status: ok means Express is up. It doesn't mean MCP is wired correctly. For that, send a JSON-RPC request.

List Tools

curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

The response is an SSE event whose data: line contains the JSON-RPC result. You should see all nine tools, each with a JSON Schema derived from Zod.

The Accept header matters. MCP Streamable HTTP can return JSON or an event stream. Asking for both is the compatible choice.

Call a Tool

curl -s -X POST http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params": {
      "name": "search_scholarships",
      "arguments": {
        "fieldOfStudy": "computer science",
        "limit": 3
      }
    }
  }'

You should get a numbered list with ids, deadlines, and GPA minimums. Copy one id and pass it to get_scholarship.

A small Node smoke test is nicer than raw curl once you're calling several methods. Parse the data: line, then print result.content[0].text. The repo includes scripts/smoke-test.js for that.

Inspector

The MCP Inspector is the official GUI for servers. Point it at http://127.0.0.1:3000/mcp and you can list tools, fill in arguments, and read resources without a host app in the way.

Use Inspector when a host "can't see" your server. If Inspector works and the host doesn't, the bug is in the host config. If Inspector fails, the bug is in your process.

How to Connect Cursor and Claude Desktop

Keep npm start running. MCP over HTTP is a live server, not a one-shot CLI.

Cursor

Add a server entry in Cursor's MCP settings. A Streamable HTTP server looks like this:

{
  "mcpServers": {
    "scholarship-research": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Restart the MCP session if Cursor had a previous failed connection cached. Then ask:

I am a first-generation undergraduate studying computer science in the United States, GPA 3.6. Use the scholarship research tools to build a shortlist and a six-week plan.

You should see the host call match_scholarships or search_scholarships, then get_scholarship for the interesting rows, then maybe save_scholarship. If it never calls a tool, the server isn't actually connected. Check the MCP logs in Cursor before you change code.

You can also invoke the research-plan prompt from the host's prompt menu if it surfaces prompts.

Claude Desktop

Claude Desktop's config file lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Desktop prefers stdio. Bridge your HTTP server with mcp-remote:

{
  "mcpServers": {
    "scholarship-research": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3000/mcp"]
    }
  }
}

Restart Claude Desktop after you save the file. The scholarship tools should appear in the tool list.

Don't put MongoDB credentials in the Claude config. The Node process already loaded .env. The host only needs the URL.

How a Research Session Runs

Here's a realistic session against the seed catalog. The student is a first-generation undergraduate in computer science, a US citizen, GPA 3.6.

The host calls match_scholarships with that profile. The server returns ranked rows. A women-in-technology award and a first-generation program both score well, for different reasons. A graduate-only award never appears.

The host then calls get_scholarship on the top two ids. Each result includes the official URL, the requirement list, and the deadline. That's the moment to tell the student to open the URL. The model shouldn't be the last word on eligibility.

If an award is worth pursuing, the host calls save_scholarship with a researcherId such as ada and status saved. Later it can set applying. list_saved_scholarships is how a new chat picks up the shortlist. Persistence is the whole point of MongoDB here. Without it, every conversation starts from zero.

add_research_note is for the messy human details: "Ask Dr. Chen for a recommendation by October 1." get_upcoming_deadlines is the weekly sweep. compare_scholarships is for the moment the student has two finalists and needs amount, GPA, and requirements in one view.

The research-plan prompt packages that loop. It injects the profile into a user message that tells the model to call tools first and then produce a week-by-week plan. If you invoke the prompt without a connected server, you get a generic essay. If you invoke it with this server running, you get named awards and real dates.

That's the product: a catalog the model can query, a shortlist it can't forget, and prompts that make the workflow repeatable.

How the Matching Logic Works

It's worth slowing down on matching, because this is the part people are tempted to hand to the model.

Suppose the student is:

• GPA 3.6

• Computer science

• Undergraduate

• United States citizen

• First-generation

• A woman

The matcher walks every open award.

A women-in-technology scholarship with a 3.3 GPA minimum, CS as a listed field, and US eligibility scores high: education, GPA, citizenship, women-only flag, and field all hit. A first-generation program that is field-open also scores high, because any counts as a field match. A graduate-only award is skipped, even if the title looks relevant. A 3.8 GPA cutoff is skipped, even if everything else fits.

The tool then returns ranked rows with reasons:

1. Palantir Women in Technology Scholarship — score 90
   Why: education level matches; GPA 3.6 meets the 3.3 minimum; citizenship is eligible; women-only award matches; field of study matches

The model can still write a warm paragraph around that. It shouldn't be the component that decided eligibility.

If you extend this later, keep the same split. New eligibility rules belong in the service. New prose belongs in the prompt.

What You Can Build Next

The server you have is complete enough to use. It's also a base for a more serious research tool.

First, you could replace the seed file with a live source. Official feeds such as Grants.gov and college-maintained lists are safer than scraping commercial aggregators. Keep your schema. Write an importer that upserts by a stable external id.

You could also add authentication. createMcpExpressApp works with requireBearerAuth. Map researcherId from the verified token instead of a tool argument. The Express adapter documents that middleware.

Try adding full-text search. The schema already has a text index. For a large catalog, Atlas Search or a dedicated search engine will beat a pile of regex filters.

You can track documents, not just notes. A documents collection for transcripts, recommendation status, and essay drafts turns the shortlist into an application tracker.

You could also write tests around the matcher. Eligibility code is where silent bugs hurt people. A table of profiles and expected include/exclude lists will pay for itself.

And you could deploy it. Bind to 127.0.0.1 on your laptop. If you put this on a network, set allowedHosts, terminate TLS, and require a bearer token. An open MCP server is an open database with a helpful English interface.

Conclusion

In this guide, you built a scholarship research MCP server that's more than a toy tool list.

You stored awards, shortlists, and notes in MongoDB. You exposed search, matching, and research-tracking as MCP tools, with Zod schemas the host can advertise to a model. You added resources for the catalog and prompts for repeatable workflows. You served the whole thing over Streamable HTTP with Express, including the Host header checks the SDK enables for localhost.

The pattern transfers. Any research workflow with a catalog and a personal working set can use the same three layers: a service that owns the rules, an McpServer factory that registers primitives, and a small Express app that speaks the protocol.

If you take one idea from this tutorial, take this one: let the model write the plan, and let your server decide what's true.

The sample catalog is for learning. Confirm every scholarship on its official application page before you apply, and before you tell someone else to apply.

Table of Contents

• MCP Server: A-Z of Model Context Protocol

• What is MCP (Model Context Protocol)?

• Architecture of MCP

• How Does MCP Work?

• MCP vs RAG

• MCP vs A2A

• Resources

• Conclusion

MCP Server: A-Z of Model Context Protocol

LLMs possess impressive knowledge and reasoning skills, which allow them to perform many complex tasks. But the problem is that their knowledge is limited to their initial training data. It means they can’t access your calendar, run SQL queries, or send an email.

It was clear that, to give the LLMs real-world knowledge, we have to provide some integrations that enable them to access real-time knowledge or perform some actions in the real world. This leads to the classic MxN problems, where developers have to build and maintain custom integrations for every combination of M models and N tools.

The image below properly demonstrates the MxN Problem:

Function calling (also known as tool calling) provides a powerful and flexible way for OpenAI models to interface with external systems and access data outside their training data. However, this feature is currently exclusive to OpenAI models, creating vendor lock-in.

That’s where MCP steps in. MCP is a write once, use anywhere approach to the problem. An app developer can write a single MCP server for any AI system to use and expose a set of tools and data. Similarly, an AI system can implement the protocol and connect to any MCP server that exists today or in the future.

What is MCP (Model Context Protocol)?

MCP is an open-source standard, developed by Anthropic, for connecting AI applications to external systems.

By using an MCP, AI applications like Claude or ChatGPT can connect to data sources like local files and databases, tools like search engines and calculators, and workflows like specialized prompts—enabling them to access key information and perform tasks.

Think of an MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, an MCP provides a standardized way to connect AI applications to external systems.

The image below will help you to better understand the MCP Server:

Architecture of MCP

The Model Context Protocol has a clear structure with components that work together to help LLMs and outside systems interact easily. An MCP follows a simple client-server architecture, which can be broken down into three simple key components:

MCP Host

The host is the user-facing AI application, the environment where the AI model lives and interacts with the user. Hosts manage the discovery, permissions, and communication between clients and servers. This ca be a chat application like OpenAI’s ChatGPT interface or Anthropic’s Claude desktop app, or an AI-enhanced IDE like Cursor & Windsurf.

MCP Client

The MCP client is a component within the host that handles the low-level communication with the MCP server. MCP clients are instantiated by host applications to communicate with particular MCP servers. Each client handles one direct communication with one server.

Here, the difference is important: the host is the application users interact with, while clients are the components that enable server connections.

MCP Server

The MCP server is the external program or service that exposes the capabilities (tools, data, and so on) to the application. An MCP server can be seen as a wrapper around some functionality, which exposes a set of tools or resources in a standardized way so that any MCP client can invoke them.

Servers can run locally on the same machine as the host, or remotely on some cloud service, since an MCP is designed to support both scenarios seamlessly

The image below will help you to better understand the concept:

An MCP server can expose one or more capabilities to the client. Capabilities are essentially the features or functions that the server makes available.

The MCP server provides the following capabilities:

• Tools: Tools are the functions that do something on behalf of the AI model. An AI can use this tool whenever required. Tools are triggered by the AI model’s choice, which means the LLM (via the host) decides to call a tool when it determines it needs to perform a specific task. For example: send_email -> send the email to the user

• Resources: Resources provide read-only data to the AI model. A resource can be a database record or a knowledge base that the AI can query to get information, but can’t modify.

• Prompts: Prompts are the predefined templates or workflows that the server can provide.

Transport Layer

The transport layer uses JSON-RPC 2.0 messages to communicate between the client and server. For this, we have mainly two transport methods:

• Standard Input/Output (stdio): Ideal for local environments, providing fast and synchronous message transmission.

• Server-Sent Events (SSE): Best suited for remote resources, enabling efficient, real-time, one-way data streaming from the server to the client.

How Does MCP Work?

An MCP gives an AI assistant the ability to securely use external tools, databases, and services. Imagine you ask Claude:

“Find the latest sales report in our database and email it to my manager.”

Step #1 - Tool Discovery

When we launch any MCP client (Claude Desktop), it connects to your configured MCP servers and asks: “What can I do with available tools?”

Each server responds with its available tools:

database_query ,email_sender ,file_browser

Now, Claude knows about the tools it has.

Step #2 - Understanding Your Requirement

Claude reads your query and realizes:

• It needs to retrieve information it doesn’t have (in this case, it has to find the sales data database_query)

• It needs to take an external action (send email email_sender )

So Claude plans a 2-step tool sequence.

Step #3 - Ask for Permission

Before any external action happens, Claude Desktop prompts you: “Claude wants to query your sales database. Allow?”

Nothing proceeds without your approval. This is core to the MCP’s security model.

Step #4 - Querying the Database

Once you grant the permission, Claude sends a structured MCP tool call to the database_query server.

Next, the server will run a secure database lookup and return the latest sales report data. This doesn’t give Claude direct access to the database.

Step #5 - Sending the Email

Once Claude has the data, Claude triggers a second permission prompt: “Claude wants to send an email on your behalf. Approve?”

Once approved, MCP sends the information to the email_sender server, and Claude will format the email & deliver it to your manager

Step #6 - Natural Answer

Claude wraps everything up nicely and sends a response to you, “Done! I found the latest sales report and emailed it to your manager.”

The entire process typically happens in seconds. From your perspective, Claude simply "knows" how to access your database and send emails, but in reality, the MCP has orchestrated a secure, standardized exchange between multiple systems.

The beauty of MCP is that it transforms AI assistants from isolated conversational tools into genuine productivity partners that can interact with your entire digital ecosystem, safely and with your explicit permission every step of the way.

MCP vs RAG

Fundamentally, MCP and RAG are built for serving different purposes.

RAG is a technique that is used to supply the relevant knowledge that we have stored in a vector database. In RAG, the user’s query is converted to a vector embedding, which searches through embeddings in the vector database and finds the relevant context based on similarity. This relevant context is then provided to the LLM. It is great for answering questions from large documents like company wikis, knowledge bases, or research papers.

An MCP enables AI models to perform real-world actions with the help of tools. It lets the AI connect to tools and services like databases, APIs, Gmail, calendar, and so on.

MCP vs A2A

The Model Context Protocol (MCP) and the Agent-to-Agent (A2A) protocol are complementary open standards in AI architecture that serve different purposes in how AI agents connect with external systems.

• MCP standardizes how a single AI agent connects to tools, data, and external systems (agent-to-tool communication).

• A2A standardizes how multiple, independent AI agents communicate and collaborate with each other (agent-to-agent communication).

Resources

For more information on the MCP, you can refer to the official website: modelcontextprotocol.io.

Some of the awesome MCP Servers which you can check:

• Brave Search MCP Server

  • An MCP server implementation that integrates the Brave Search API, providing both web and local search capabilities.

• Sentry MCP server

  • This server provides tools to inspect error reports, stacktraces, and other debugging information from your Sentry account.

• Google Maps MCP Server

  • MCP Server for the Google Maps API.

• Tailwind MCP Server by FlyonUI

  • MCP Server for FlyoUI - Generate Amazing UIs/Themes/Sections with just a single prompt.

• git MCP server

  • A Model Context Protocol server for Git repository interaction and automation. This server provides tools to read, search, and manipulate Git repositories via Large Language Models.

• GitHub MCP Server

  • MCP Server for the GitHub API, enabling file operations, repository management, search functionality, and more.

• Shadcn MCP Server

  • MCP Server for shadcn/studio - Generate Amazing UIs/Themes/Sections with just a single prompt.

You can explore a list of available MCP servers here: https://github.com/punkpeye/awesome-mcp-servers

If you're interested in learning how to build your own MCP server, check out this detailed course on Hugging Face: https://huggingface.co/mcp-course.

Conclusion

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. With MCP, AI models are not just chatbots, they are fully capable agents that can work with your local files, query your database, send emails with your permission and control.

It has also solved the classic MxN problem—developers only need to build the MCP server once, then all other AI systems can integrate the MCP server in their application.

MCP is the revolution in how AI systems can interact with the real world. As the ecosystem of the MCP continues to grow, it will enable AI agents to become more powerful assistants that can operate across diverse environments with reliability and security.

But there’s one major limitation that still holds them back: context.

Most AI models don’t have access to your system, files, APIs, or live data. They only know what you tell them in a prompt.

The Model Context Protocol, also known as MCP, was created to address this problem. It enables AI models to securely connect to your own tools, APIs, and systems via small, structured servers known as MCP servers.

In this guide, you’ll learn how to build your own MCP server using Python. We’ll walk through each part of the code and I’ll explain how it works.

By the end, you’ll have a running MCP server that can add numbers, return random words, and fetch live weather data from the internet. We will also see how to host this MCP server on the cloud.

What we’ll cover:

• What is Model Context Protocol?

• Setting Up Your Environment

• Creating the Project

• Configuring Logging

• Creating the MCP Server

• Defining Tools

  • Example 1: Adding Two Numbers

  • Example 2: Returning a Random Secret Word

  • Example 3: Fetching Weather Data

• Running the Server

• Testing the Tools

• Deploying Your MCP Server to Sevalla

• Why Build Your Own MCP Server

• Expanding the Server

• Conclusion

What is Model Context Protocol?

Before diving into the code, it’s important to understand what the Model Context Protocol actually is.

MCP is an open standard that defines how AI models and external systems communicate. You can think of it as an API that’s designed specifically for AI assistants.

If an API lets two software programs exchange data, MCP allows an AI model to talk to your system. This opens up endless possibilities.

You could build an MCP server that lets ChatGPT read files from your local machine, or one that calls your company’s internal APIs to fetch data. You could even expose your own Python functions so that a model can use them as tools.

MCP makes this communication structured, secure, and extendable. It runs on familiar web technologies such as Server-Sent Events, or SSE, which allow the server to send real-time data streams to the client.

Setting Up Your Environment

To follow along, you’ll need Python version 3.9 or higher. You can find the code for this example in this repository.

We’ll use a library called FastMCP that simplifies the process of building MCP servers. You can install it using pip:

pip install fastmcp requests

The requests library will be used to make HTTP calls later in the example. Once installed, you’re ready to create your first MCP server.

Creating the Project

Create a new file called server.py and start by importing the necessary modules:

import logging
import os
import random
import sys
import requests
from mcp.server.fastmcp import FastMCP

Here’s what each one does:

• The logging module records what your server is doing.

• os is used to access environment variables like port numbers.

• random will help us generate random words.

• sys allows the script to exit gracefully in case of errors.

• requests lets us fetch live data from APIs.

• And finally, FastMCP turns our Python functions into tools that can be called through the MCP protocol.

Configuring Logging

Logging gives you visibility into what your server is doing. It helps during development and is vital when you deploy your server in production.

name = "demo-mcp-server"
logging.basicConfig(
    level=logging.INFO,
    format='%(name)s - %(levelname)s - %(message)s',
    handlers=[logging.StreamHandler()]
)
logger = logging.getLogger(name)

This configuration prints log messages to the console in a simple format showing the server name, the log level, and the message. Every time a tool runs, a message will appear in the logs such as:

demo-mcp-server - INFO - Tool called: add(3, 5)

Creating the MCP Server

Next, we’ll create the server instance that will host our tools.

port = int(os.environ.get('PORT', 8080))
mcp = FastMCP(name, logger=logger, port=port)

The server will run on the port specified by the environment variable PORT. If that variable isn’t set, it defaults to 8080. The FastMCP object now represents your running MCP server.

Defining Tools

Each function that you decorate with @mcp.tool() becomes an accessible tool that clients can call. Let’s start with a simple example: an addition tool.

Example 1: Adding Two Numbers

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    logger.info(f"Tool called: add({a}, {b})")
    return a + b

This tool takes two numbers, logs the call, and returns their sum. Calling add(3, 5) will return 8.

Even though it’s simple, this shows the basic structure of every MCP tool: input parameters, a logging statement, and a return value.

Example 2: Returning a Random Secret Word

Let’s make another tool that returns a random word from a small list.

@mcp.tool()
def get_secret_word() -> str:
    """Get a random secret word"""
    logger.info("Tool called: get_secret_word()")
    return random.choice(["apple", "banana", "cherry"])

When you call this function, it picks one of the three words at random. Each time you call it, you might get a different result. This function demonstrates how MCP tools can use logic or randomness just like any regular Python function.

Example 3: Fetching Weather Data

Now let’s build something more practical. We’ll create a tool that fetches live weather data from the web using the requests library.

@mcp.tool()
def get_current_weather(city: str) -> str:
    """Get current weather for a city"""
    logger.info(f"Tool called: get_current_weather({city})")

try:
        endpoint = "https://wttr.in"
        response = requests.get(f"{endpoint}/{city}", timeout=10)
        response.raise_for_status()
        return response.text
    except requests.RequestException as e:
        logger.error(f"Error fetching weather data: {str(e)}")
        return f"Error fetching weather data: {str(e)}"

This tool accepts a city name, sends a request to the public weather service at wttr.in, and returns the text-based weather report. If there’s any issue, such as a network timeout or invalid city name, the function logs an error and returns a descriptive message.

Calling get_current_weather("London") will print a short weather summary for that city.

Running the Server

Once all your tools are defined, you can start the server. Add the following code to the bottom of your file:

if __name__ == "__main__":
    logger.info(f"Starting MCP Server on port {port}...")
    try:
        mcp.run(transport="sse")
    except Exception as e:
        logger.error(f"Server error: {str(e)}")
        sys.exit(1)
    finally:
        logger.info("Server terminated")

This block starts the server using the Server-Sent Events transport method. If anything goes wrong, it logs the error and shuts down cleanly.

You can now run the server from your terminal:

python server.py

If everything is working, you’ll see:

demo-mcp-server - INFO - Starting MCP Server on port 8080...

Your MCP server is now live and ready to accept requests.

Testing the Tools

To test your tools, you need an MCP-compatible client such as ChatGPT with developer features or another app that supports the protocol. Once connected, the client will list your available tools.

For example, you can send a request like this:

{
  "tool": "add",
  "args": [5, 7]
}

The server will respond with:

{
  "result": 12
}

The same applies to the other tools such as get_secret_word or get_current_weather.

If you want to test the server directly without the MCP client, you can still send HTTP requests manually (though this bypasses the full protocol logic).

For example, to test your weather tool, you can send a simple GET request:

curl http://localhost:8080/tool/get_current_weather?city=London

or in Python:

import requests
response = requests.get("http://localhost:8080/tool/get_current_weather", params={"city": "London"})
print(response.text)

This won’t use the MCP structure (like sse streaming), but it’s a quick sanity check that your server works.

Deploying Your MCP Server to Sevalla

You can run this server locally for development. But if you want to use it in production applications, you have to deploy it to a server.

You can choose any cloud provider, like AWS, Heroku, or others to set up this project. But I will be using Sevalla.

Sevalla is a modern, usage-based Platform-as-a-service provider. It offers application hosting, database, object storage, and static site hosting for your projects.

I am using Sevalla for hosting for two reasons:

• Every platform will charge you for creating a cloud resource. Sevalla comes with a $50 credit for us to use, so we won’t incur any costs for this example.

• Sevalla has a template for Python MCP server, so it simplifies the manual installation and setup for each resource you will need for installation.

Log in to Sevalla and click on Templates. You can see Python MCP Server as one of the templates.

Click on the “Python MCP Server” template. You will see the resources needed to provision the application. Click on “Deploy Template”.

You can see the resource being provisioned. If the deployment doesn't start automatically, click “Deploy now”.

Wait for a few minutes. Once the deployment is complete, you will see a green checkmark.

Once deployment is complete, click on “Visit app”. You will get a cloud url eg. https://python-mcp-server-rlfdk.sevalla.app. Use this as the base url instead of the localhost:3000 url.

You now have a production-grade MCP server running on the cloud. You can plug this into any application to fetch data for our LLM applications.

Why Build Your Own MCP Server?

Building an MCP server gives you control and flexibility.

You can connect AI models directly to your databases or internal systems, automate repetitive actions, and decide exactly what data an AI model can access.

It also allows you to experiment quickly. You can start small with a few simple tools and expand later into complex workflows.

By creating your own MCP server, you’re not just writing code – you’re defining how intelligent systems interact with the real world through your logic and data.

Expanding the Server

Once you’ve mastered the basics, it’s easy to extend your server. You can add tools that read and write files, query databases, interact with APIs like GitHub or Slack, or monitor your system. Each new function becomes another tool that your AI can use.

This modular approach lets you build an entire ecosystem of AI-aware tools, each performing a specific task but working together through the same MCP interface.

Conclusion

In this tutorial, you learned how to create an MCP server in Python using the FastMCP library. You configured logging, set up a server, defined multiple tools, and learned how to run and test it. You also saw how easily these tools can expose real functionality, like fetching live weather data or performing basic computations.

This structure is simple yet powerful. With just a few lines of Python code, you can build bridges between your systems and intelligent models. The Model Context Protocol represents a step toward AI systems that can truly understand and interact with real-world data and actions.

Hope you enjoyed this article. Signup for my free newsletter TuringTalks.ai for more hands-on tutorials on AI. You can also visit my website.

Here’s what we’ll cover:

• Prerequisites

• What is the Model Context Protocol (MCP)?

  • What does "Protocol" mean?

  • What is a "Model"?

  • What is "Context"?

  • Putting It All Together: What is Model Context Protocol?

• Why MCP is Necessary

  • The MCP Connector in Action

  • Universal Access Across Platforms

  • Developers are Key

  • Beyond Built-in Integrations

  • The Power of Reusability

  • The Burden without MCP

  • A Practical GitHub Example

  • Why MCP Matters for Developers

• RAG vs MCP

  • What is RAG

  • RAG: The “Mise en Place” Prep

  • MCP: The Rolling Assistant Cart

  • Bringing It All Together

• MCP Documentation

• How AI Apps Talk to MCP Servers — A Practical Example

  • Scenario: Asking Claude About Your Schedule

  • Discovering the Right MCP Server

  • MCP Server Fetches and Returns the Data

  • Model Converts Structured Data into Natural Language

  • Under the Hood: Abstracting the Complexity

  • Mirroring Standard Web App Workflows

• How MCP Servers Work Internally

• The MCP Architecture — How It All Fits Together

  • 1. MCP Host

  • 2. MCP Client

  • 3. MCP Server

  • 4. Data Sources – Local or Remote

• Opportunities for Web Developers

  • SDK Options: Pick Your Language

  • From Backend Service to AI-Enabled Developer

• MCP Server Setup and Integration

• Summary

Prerequisites

To follow along and get the most out of this guide, you should have:

1. Basic understanding of TypeScript or JavaScript: While we’ll use TypeScript here, knowledge of JavaScript alone is enough to follow the examples.

2. Familiarity with Node.js and npm: You should know how to initialize a project, install packages, and run scripts using node and npm.

3. Experience with working in the terminal/command line: Especially for understanding concepts like stdin and stdout, and running local servers.

4. Comfort with environment variables (.env files): You’ll be setting API keys and other sensitive data in a .env file.

5. Basic knowledge of REST APIs and HTTP concepts: This helps in understanding how we used AI tools to fetch context before MCP and why MCP simplifies the process.

6. Familiarity with Google Cloud / API Console (optional but recommended): Since this handbook involves integrating with Google Calendar, you should know how to:

   • Generate a public Google API key

   • Find or create a Google Calendar and access its ID

7. Cursor editor installed (optional but recommended): To follow the final integration steps with the AI-powered code editor.

8. Some exposure to AI tools like Claude, Cursor, or ChatGPT: This helps you grasp how MCP bridges external data with AI context.

I’ve also created a video to go along with this handbook. If you’re the type who likes to learn from video as well as text, you can check it out here:

What is the Model Context Protocol (MCP)?

Let's start from the very beginning: what exactly is the MCP? MCP stands for Model Context Protocol. And if we break it down word by word – "model", "context", and "protocol" – it actually becomes quite easy to understand.

But before diving in, here's a quick background: Model Context Protocol was developed by a company called Anthropic. You've probably heard of them. They're the ones who built Claude, the popular AI assistant. They first introduced MCP in November of 2024, and in a short time it’s become a standard adopted by tons of other companies as well, including Microsoft.

Now, let's explore what MCP really means by understanding each term.

What does "Protocol" mean?

Let's start with the last word: Protocol. What does "Protocol" mean? Well, it’s a set of rules.

As developers, we work with protocols all the time. For example, when we work with the HTTP protocol, it's not just random communication – there's a set of rules we follow. When we build REST APIs, we use specific methods like GET, POST, PUT, PATCH, or DELETE. We transfer data in specific formats like JSON, XML, or even JSON-RPC. All of this is structured communication that follows a protocol.

In a similar way, AI agents or AI-based applications also need to follow a structured approach when exchanging information. We'll explore that more in a bit, but for now, just remember: a protocol is simply a set of rules.

What is a "Model"?

Next, let's talk about the “Model”. The term "Model" is something you’re likely already quite familiar with. We all use models in one way or another, especially large language models or LLMs.

Take GPT from OpenAI, Gemini from Google, Claude from Anthropic – you may use these every day. There are tons of models available now, like the newer DeepSeek and so on. The point is, we already interact with models regularly. We ask questions, and they give us answers.

But have you ever wondered how these LLMs actually work? Most people think that when you ask a model something, it goes and searches the internet for answers. But that's not how it works.

What these models actually do is predict the next word in a sentence – that's it. They're language experts – they don't know "facts" in real-time or pull live data from the web. Instead, they've been trained with a huge amount of information beforehand (pre-trained). Then when you ask something, they try to figure out: "What word most likely comes next based on what the user just said?"

That's why when you ask something, the reply appears word by word – like it's typing. And no, that's not some fancy frontend animation. That's just how LLMs work: they predict one word at a time. It looks like typing because it is being generated in real time, one word at a time.

That's the core of Generative AI. They're experts in natural language – understanding how we speak, predicting what we're likely to say next and generating responses accordingly.

What is "Context"?

Now let's move to “Context”. In English, context means the subject or background of something. For example, when you send an email, you add a subject line. And just by looking at the subject, the recipient gets an idea of what the email is about – even before opening it.

Similarly, when you talk to a model like ChatGPT or Claude, you provide a few lines – maybe a question or some background. That input becomes the “Context”.

The model's response entirely depends on the context you provide. It uses that context to start predicting the next word. If the model already knows what you're referring to, based on the context, it'll give you an accurate answer. But if you don't provide enough context, it can't help you properly – even if it's a powerful LLM.

Let me give you a simple example: Suppose you go to Claude and ask, "Who am I?" Will it be able to answer that? No, it won't. But if in a previous message you had told Claude, "Hey, I'm Sumit" and then later in the same session ask "Who am I?", it will say, "You're Sumit." Why? Because now it has context.

So, context is just background info – and the better context you give, the better the model can respond. That's how these LLMs are designed to work.

Putting It All Together: What is Model Context Protocol?

So when we say “Model Context Protocol”, we're talking about a set of rules or protocols that define how to feed context into a model. Now, what is this context we're feeding? It could be any kind of external information – something outside the model's default knowledge.

It’s like going to Claude Desktop and telling it, “Hey, I’m Sumit!” and then asking "Who am I?". Again, it’ll know because you told it before.

But here's the catch: models don't magically know about your calendar, your emails, your databases or your files. So how do you make that data available to them? That's where MCP comes in.

MCP lets us feed these external pieces of information – like your schedule, your project data, or anything else – into a model, but in a structured and standardized way. And that's what makes MCP so powerful.

Why MCP is Necessary

Now that you understand what MCP is, let's talk about why we need it. Why did Anthropic even invent this thing in the first place?

Let's think about how we use different code editors in our day-to-day work. One really powerful, AI-equipped modern code editor is Cursor. Personally, I don't use it regularly, but it’s perfect for this demonstration. Imagine you are inside your Cursor editor. And, as many of you know, you can chat with Cursor while coding. You can ask it to explain something, generate code, refactor logic, and so on.

The MCP Connector in Action

Now let's say you ask Cursor something that depends on data from your local machine – maybe a large email database or your own personal documents. Can Cursor access that data by default? No, it can't. But what if – and this is the important part – what if you connect a custom-made component to Cursor?

Let's call it an MCP server. If you connect your MCP server to Cursor, then here's what happens: Cursor still can't access your files directly. But now, when you ask it a question, it will turn to this MCP server and say: "Hey, do you know anything about this?" And the MCP server – since you've built it to connect with your files or databases – will fetch the relevant information, turn it into context, and feed that back to the model. Now the model has the necessary background to generate a smart, informed reply.

And the best part? You're not limited to just one connector. You can connect multiple MCP servers to your application.

Universal Access Across Platforms

Let's now walk through a real example – something I'll actually show you later with code examples in this handbook.

Say you ask Cursor: "Do I have any meetings today?" Now to answer that, the AI would need access to your schedule, right? Let's say you use Google Calendar to manage your meetings. Can Cursor directly connect to your Google Calendar? No, it can't. And not just Cursor – ChatGPT or Claude can't access your calendar either, not unless you manually build that integration.

But here's the thing: what if you want this to work universally? Like, no matter where you ask the question from? You might ask it from Cursor today, but someone else might ask from ChatGPT tomorrow.

In both cases, we want these tools to access your calendar and return the same result. To make that possible, we need a universal way to connect – and that's exactly what an MCP server enables. If you create an MCP server that follows the protocol and hooks into your calendar, then any AI application that supports MCP can connect to it and get the right context. That's another reason MCP is so powerful.

Developers are Key

And the best part? You (the developer) are the one who will build these MCP servers. This isn't something regular users can build – you need coding skills for this.

This is one reason AI won’t replace developers just yet :)

Beyond Built-in Integrations

Let's compare that with what used to happen before. For example, today, ChatGPT lets you do web searches – you can just ask it to find something online, and it'll fetch the result. But this feature is only there because OpenAI, the makers of ChatGPT, built it into the app.

Now imagine your own product – like my logicBase Labs website. Let's say students come to the site and ask questions through a chat box you’ve built. That AI assistant belongs to you – it's part of your software. You can connect it to any model, like GPT, Claude, whatever, that understands natural language. But you still need to feed it the right information so it can respond meaningfully.

So what do you do? You build your own MCP server, maybe using Node.js, Python, or Java – whatever tech stack you're comfortable with. This MCP server is a completely standalone app. Now you also build your chat interface – the UI where students type questions. You connect it to the LLM (like GPT or Claude) and to your custom-built MCP server.

The Power of Reusability

Here's the best part: your MCP server is now independent and reusable. You could even give it to another company, like another EdTech company wants to use your calendar or data handling logic. They can just modify your MCP server, replace the logic with their own data, and use it with their chat client. And boom – it's a universal solution now.

Even better, let's say the data inside my logicBase Labs website changes in the future. No problem! I won’t need to rewrite the connector logic. The code that fetches and formats the data stays the same. The content might change, but the structure is stable.

The Burden without MCP

But if I wasn’t using MCP, what would I have to do? I’d need to build everything into my client. Every AI assistant would need to carry the burden of logic, context building, and data retrieval. If anything changed – say the GitHub repo’s structure, the schedule format, or the database schema – I’d have to go and update every single client individually. That's a nightmare!

A Practical GitHub Example

Let me give you another solid example. Suppose you want to connect your GitHub to Cursor. You want to say something like: "Hey, push my code to GitHub" – and it just works. To make that happen without MCP, what would you normally need to do? You'd have to:

• Read through the GitHub API documentation

• Write integration logic

• Handle OAuth authentication

• Deal with access tokens and API limits

It's complex. It's messy. But imagine this: What if GitHub themselves released their own MCP server? Then all you need to do is:

• Plug that MCP server into Cursor

• Let the model discover the capabilities

• Say: "Push my code"

And boom – it works! You don't need to write any custom integration logic. That's the magic of MCP. And here's the best part: GitHub already released their official MCP server. You can use it right now.

Why MCP Matters for Developers

So I hope you now see the bigger picture. MCP servers are a game-changer. They don't just reduce your workload – they create new job opportunities for developers like us. This isn't going to "replace your job". Rather, it's creating new, valuable work that didn't exist before.

RAG vs MCP

Now that we’ve covered MCP, let’s look at another popular approach called RAG and see how they differ. Many AI builders start by using RAG to ground their models in static knowledge, so it’s helpful to see how that approach compares to streaming live data with MCP.

What is RAG?

First up, what is RAG? Retrieval-Augmented Generation is a technique in which an AI model reaches out to an external “library” of documents at the moment you ask a question. It pulls back just the pages it needs, tucks them into your prompt and then writes its answer using those exact excerpts. In other words, it dynamically augments itself with relevant text from a large corpus.

RAG: The “Mise en Place” Prep

Imagine you’re the head chef preparing for service. Before the doors open, you and your team do a full mise en place: chop, measure, and arrange every ingredient on your counter so it’s ready the moment you need it. When orders start flying in, you simply grab what’s already laid out – no running back to the pantry.

How it works:

1. Retrieve: Your system searches a document store for the most relevant “ingredients” (text snippets).

2. Augment: Those snippets get mixed into your AI prompt.

3. Generate: The model cooks up an answer grounded in that batch of information.

RAG is great for static or rarely changing content (think policy manuals, research papers, or any “recipe book” that doesn’t get rewritten mid-service).

MCP: The Rolling Assistant Cart

Now imagine halfway through dinner you realize you need a fresh herb or a special garnish that wasn’t prepped. Instead of halting the kitchen, you wheel over an assistant cart loaded with whatever new items appear – they bring you that garnish the second it’s ready.

How it works:

1. Subscribe/Stream: Your AI client opens a live line to the data source.

2. Deliver: As soon as new data (like a live order update or sensor reading) is available, it rolls up to you.

3. Consume: Your model can tap into that fresh data anytime during generation.

MCP is great for scenarios needing up-to-the-minute info (like live dashboards, chatbots feeding off recent user activity, IoT sensor streams, and so on).

Bringing It All Together

• RAG alone: Best when your "mise en place" is extensive enough to cover everything you need – pre-prepared background knowledge.

• MCP alone: Required when you need “a rolling cart” of fresh ingredients at one's fingertips.

• Combined approach: Do your background “mise en place” with RAG for in-depth context, and keep the assistant cart rolling with MCP to provide live updates – so your AI has deep background knowledge along with real-time freshness.

MCP Documentation

Now let's check out the official MCP documentation. It’ll help things start to feel much clearer. So what does the definition say?

MCP is an open protocol that standardizes how applications provide context to LLMs. (Source: MCP Documentation)

Yep – exactly what we've already talked about. And then comes a brilliant line from the docs:

Think of MCP like a USB-C port for AI applications. (Source: MCP Documentation)

Let's pause here, because this analogy is super important. Think about the USB-C port on modern devices. We all use it. But remember how things were before? Back in the day, your computer would have tons of different ports – HDMI, VGA, USB-A, audio jack, you name it. You'd have to manage different cables for everything. Maybe your mouse was USB-A, your keyboard used some other port, and your external monitor needed HDMI. It was a mess.

But now? Everything uses USB-C. One universal connector for data, power, audio, video – everything. That's exactly what MCP is for AI applications. Instead of building separate integrations or connectors for each AI tool (Cursor, ChatGPT, Claude, and so on), you now build one standardized MCP server and any AI tool that supports MCP can connect to it. That's why this protocol is such a big deal.

How AI Apps Talk to MCP Servers — A Practical Example

Let me walk you through one more example just to help you really get this. Imagine you're using Claude. You ask it a simple question: “Do I have a meeting today?"

Scenario: Asking Claude About Your Schedule

Now, Claude doesn't actually have that information. If you haven't connected any MCP server, it'll give you a vague answer. Probably something nice and generic, because it's good at natural language – but not specific. But if you want a real answer – something factual – you need to feed it context. And that's where the MCP server steps in.

Discovering the Right MCP Server

Let's say Claude is connected to an MCP server. Now things get interesting. As soon as you ask the question, Claude will first look at the list of MCP servers it's connected to. Then it'll intelligently choose the right one and ask:

"Hey, what are your capabilities?"

Because your MCP server might be able to do many things. Maybe it can:

• Give a full list of calendar events

• Check if there's a meeting on a specific day

• Fetch data from Google Calendar

• Summarize documents

So the model first figures out:

"Which of these capabilities do I need?"

In this case, it decides:

"Okay, I just need to know if the user has a meeting today."

Then Claude sends a message to the MCP server – in a specific format, which we'll look at shortly. It's kind of like how REST APIs work. The message says something like:

"Here's the date. Tell me if the user has a meeting."

MCP Server Fetches and Returns the Data

Now the MCP server takes that input, connects to Google Calendar (or whichever source you've set it up with) and runs the necessary logic. Eventually, it sends back a response, usually in a structured format like JSON-RPC. It might return a list of meetings or just one – whatever applies.

Model Converts Structured Data into Natural Language

Now here's the beauty of it. Even though the MCP server is giving back something technical (like JSON), Claude will never show that to the user. Because it's a language model, it will convert that structured data into a smooth, natural sentence like:

"Yes, you have a meeting with Dr. Chuck at 4 PM."

Under the Hood: Abstracting the Complexity

To the user, it feels like magic. But behind the scenes, a lot just happened:

• The model found the right MCP server

• It selected the right capability

• It passed the correct input

• The server ran logic, got the data, and returned a structured result

• And finally, the model turned that into human language

Mirroring Standard Web App Workflows

This is exactly how our websites work too. Let's say a user visits your website and types something in a message box. You fetch data in the backend, maybe call an API or run a DB query. That response comes back in JSON — but the user never sees that. What they see is the final polished UI response. Same principle here. So I hope it's now clear how powerful this system is.

How MCP Servers Work Internally

Now let's go one step deeper and understand how an MCP server actually works under the hood – technically. An MCP server primarily works through something called standard input and output, or in programming terms, stdin and stdout. So what does that mean? Let's break it down with an example.

You know when you open a terminal in the Cursor editor, it gives you a basic shell where you can type in commands? That terminal is using your machine's standard input and output system.

Now typically, when websites communicate with APIs, they use REST APIs over HTTP. But with MCP servers – especially when they're used locally – we don't use HTTP. Here's why: many times, your MCP server is running on your own machine, connected to local databases or files. So instead of going through network calls, it uses direct system-level communication through stdin and stdout.

Let's say you're inside Cursor, and you type something like:

echo "hello"

What happens? The terminal reads your input (stdin), processes it and prints hello back to you via stdout. This same pattern is used by MCP servers.

Now imagine the AI application (like Claude) is trying to talk to your MCP server. How does it do that? It doesn't send an HTTP request like a web client. Instead, it writes the request directly into the MCP server's standard input – just like how a terminal command works. And then your MCP server reads that input, performs the necessary action (maybe it talks to Google Calendar, a database, a filesystem, whatever) and once it's done, it sends the response back using standard output.

Let's imagine a real-life conversation between Claude and your MCP server. You ask Claude:

"Do I have a meeting today?"

Claude realizes it doesn't have this information on its own. So what does it do? First, it discovers the tools or methods available – it checks all connected MCP servers to see what they can do. Then it intelligently figures out the best method to use. Let's say it figures out:

"Alright, I should call the calendar method."

It then writes a structured input into your MCP server's stdin, something like:

{
    "method": "calendar",
    "params": {
        "date": "2025-06-16"
    }
}

Okay, the real format may differ, but conceptually it's like this. Your MCP server then receives that input, runs the logic, maybe pulls data from your Google Calendar, and then responds like this:

{
    "result": {
        "meetings": [
            {
                "title": "Team Sync",
                "time": "4:00 PM"
            }
        ]
    }
}

Now here's the kicker: Claude doesn't show this JSON to the user.

It reads that raw data, runs its natural language model, and finally says:

"Yes, you have a meeting 'Team Sync' today at 4 PM."

That's the entire lifecycle. And the user? They don't even know what's going on behind the scenes. Just like when a non-technical person uses your website, they don't know about fetch calls or JSON responses. They just see a smooth UI. Same deal here.

And this stdin/stdout approach works great locally – especially for data on your machine. Later, we'll see how things work differently when you connect to remote services. But for now, just remember:

MCP doesn't use HTTP calls for local communication. It works through the terminal – stdin and stdout.

And that makes it fast, secure, and incredibly flexible.

The MCP Architecture — How It All Fits Together

Let's now take a look at the MCP architecture. Once you see the structure, everything we've discussed will make even more sense. Here's what the diagram shows (the diagram was collected from the MCP documentation):

We have a host – that could be Claude, or any AI-powered application. This host is connected to one or more MCP servers through the MCP protocol. And these MCP servers are in turn connected to external data sources, which could be local files or remote services like APIs, calendars, databases, and so on.

Now what does the MCP server do? It retrieves data from those external sources, prepares the appropriate context, and feeds it back to the host using the MCP protocol. That context is then used by the LLM to generate a relevant, natural-sounding response.

All this communication – at least when done locally – happens via standard input and output (stdin and stdout) like we discussed earlier.

Let's go over the components one by one.

1. MCP Host

First, we have the MCP host. This is the AI application, something like Claude, Cursor, or even your own AI interface. If we compare this to traditional web architecture, the host is like the server of your website – the main brain that runs the show. In the context of Cursor, the Cursor editor itself is the MCP host.

2. MCP Client

Next, we have the MCP client. So what's the client in this context? Well, in web development, think of a user's browser as the client – not the user themselves, but the actual browser that sends requests and receives responses. In the MCP world, the MCP client is the internal part of the host that connects to MCP servers.

Let's take Cursor again as an example.

If you go into Cursor's settings, you'll see something called MCP Tools. That's where you can add any custom MCP server. Cursor has a built-in client that lets you plug in your own server. If you were building your own editor like Cursor, you'd need to write this client logic yourself to handle things like discovering servers, formatting requests, and reading responses. Good news is, there's already a spec and libraries to help with that too.

3. MCP Server

Then, of course, comes the MCP server, which we've already talked about at length. It's the tool you build that knows how to fetch or generate context from files, APIs, calendars, anything. You can make it with Node, Python, Java – anything you like. As long as it follows the protocol, it'll work. And remember – it can be reused across different AI apps. That's the beauty of MCP.

4. Data Sources – Local or Remote

Last but not least, we have the data sources. Your MCP server needs to pull data from somewhere. That "somewhere" could be:

• A local SQLite or Postgres DB

• Your file system

• An external API like Google Calendar or GitHub

• A third-party SaaS dashboard

• Anything else that holds relevant context

The point is: you abstract away the data handling into your MCP server. So the AI host doesn't care how the data is fetched – it just gets structured context in return.

So to recap:

• The MCP host is your AI application (like Claude, Cursor, or a custom app).

• The MCP client is the bridge inside that host that connects to external MCP servers.

• The MCP server is what you, the developer, build – to deliver context.

• And the data sources are whatever backend services or files hold your knowledge.

Everything talks to each other via the MCP protocol. And locally, it all happens through stdin/stdout, like a conversation between programs in the terminal. So that's the whole summary in one go. I hope you understand how it all works.

Opportunities for Web Developers

SDK Options: Pick Your Language

Alright, soon we will start building an MCP server – and for that, we'll be using the TypeScript SDK. Now, if you look at the documentation, you'll notice that there are many SDKs available. You can build MCP servers using:

• C#

• Java

• Kotlin

• Python

• Ruby

• Swift (for mobile)

• and of course, TypeScript – which is essentially JavaScript with superpowers!

And since JavaScript is like my mother tongue, I'll naturally go with TypeScript here. Now, don't worry – this won't be super technical. I'm not going to sit and code line-by-line with you, but I will walk you through the important parts so you get a clear understanding.

From Backend Service to AI-Enabled Developer

What you'll find is that everything we'll be doing here is stuff you likely already know. Because this is still just regular coding. You're going to build a backend service – just like one you may have done hundreds of times before. The only difference is that now, your application will be part of the MCP ecosystem.

Think of it like this: As a developer, you're not switching careers. You're not abandoning your current skills. You're still doing what you've always done – writing logic, structuring data, managing APIs. The only shift is in where you're plugging that code in. Instead of just serving HTTP requests or returning React components, now your code will be used to feed context into LLMs. And that, right there, is the bridge into the AI world.

Let's be real: in today's world, just building yet another CRUD application isn't enough. If your app isn't deeply integrated into the AI ecosystem, it's going to get left behind. But if you understand concepts like MCP, and if you know how to build and expose structured context to any model, then you're not just a developer anymore. You're an AI-enabled developer!

You're building the infrastructure that connects real-world data to AI applications. And that's huge! That's why I truly believe this whole MCP ecosystem is going to explode in the coming months and years. I believe companies all over the world are going to start building and publishing their own MCP servers – just like how everyone now builds APIs or SDKs. Soon, we'll reach a point where people won't visit your company website to fill out a form or read static FAQs. They'll just ask a question inside ChatGPT**,** Claude**,** or Cursor, like:

"What are the pricing plans for logicBase Labs?"

And they'll get a response – not because those models are trained on your website, but because you've built an MCP server that gives them real-time, personalized, authenticated data.

So yes, now let's go ahead and build our first MCP server – quickly and in a way that's easy to follow. Because ultimately, this is where developers like you belong: bringing together the best of your existing skills and applying them inside the AI universe.

MCP Server Setup and Integration

So, to build an MCP server, we've landed on the official GitHub repo page for MCP's TypeScript SDK. Now, for those of you who don't know TypeScript, there's nothing to worry about. Because TypeScript is basically a superset of JavaScript. So even if you're not familiar with TypeScript, it's totally fine. You can write your code in plain JavaScript, and since every valid JavaScript code is also valid TypeScript, you're good to go.

And if you're a regular JavaScript developer, you'll find everything here familiar – just like you'd expect from any typical docs. They've provided a small, simple template for a TypeScript server. It's a single, minimal server setup, and that's exactly the template I would use to build my own server. Let's walk through the setup.

My project is a Node.js project. I've created a server.js file, and honestly, that's the only file I've used in this project. All the code is written inside that one file.

Step-by-step, here's what I did:

1. Initialize the project

npm init

This creates the package.json file.

2. Install the required MCP package

Run the install command (mentioned in the docs).

npm install @modelcontextprotocol/sdk

3. Import and create the MCP server

I imported McpServer from the installed package and then created a new instance using new McpServer(). You need to pass an object with a name and version:

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

// create the MCP server
const server = new McpServer({
    name: "Sumit's Calendar",
    version: "1.0.0",
});

4. Add a tool (function)

Tools are the functions your AI client can invoke. I used server.tool() function from the SDK and passed three things:

• A meaningful name: getMyCalendarDataByDate so that my AI application can understand which tool to call

• Input validation using zod

• An async callback function that fetches meeting data

// register the tool to MCP
server.tool(
    "getMyCalendarDataByDate",
    {
        date: z.string().refine((val) => !isNaN(Date.parse(val)), {
            message: "Invalid date format. Please provide a valid date string.",
        }),
    },
    async ({ date }) => {
        return {
            content: [
                {
                    type: "text",
                    text: JSON.stringify(await getMyCalendarDataByDate(date)),
                },
            ],
        };
    }
);

The callback receives the validated date and uses it to call an async controller function called getMyCalendarDataByDate that fetches data from Google Calendar. Now we will write the function.

5. Google Calendar Integration

First we need to install the googleapis package with the below command in the terminal:

npm install googleapis

Then import google object from the installed the package.

import { google } from "googleapis";

Now let’s write the function getMyCalendarDataByDate and call the google.calendar method according to Google Calendar API. This google.calendar() method receives an object as parameter and we need to mention version and auth here. version is simply the Calendar API version number and auth is the Google API Public Key for authentication.

async function getMyCalendarDataByDate(date) {
    const calendar = google.calendar({
        version: "v3",
        auth: process.env.GOOGLE_PUBLIC_API_KEY,
    });
}

Here, you can see that I’ve used the Google API public key as an environment variable. So, we’ll create a .env file in the root of the project directory and add the following inside that file:

GOOGLE_PUBLIC_API_KEY=WRITE_YOUR_GOOGLE_PUBLIC_API_KEY

Don’t forget to replace with your own Google Public API Key. You can grab your public key from Google Cloud Console.

Now we need to calculate the start and end of the given date (UTC) received as string in the date parameter of the getMyCalendarDataByDate function.

// Calculate the start and end of the given date (UTC)
const start = new Date(date);
start.setUTCHours(0, 0, 0, 0);
const end = new Date(start);
end.setUTCDate(end.getUTCDate() + 1);

Now it’s time to fetch the list of events from my Google Public Calendar. For that, according to Google Calendar API, we need to call the calendar.events.list function and pass necessary options to it:

const res = await calendar.events.list({
    calendarId: process.env.CALENDAR_ID,
    timeMin: start.toISOString(),
    timeMax: end.toISOString(),
    maxResults: 10,
    singleEvents: true,
    orderBy: "startTime",
});

Here you can see, I have mentioned my Public Calendar ID using another environment variable called CALENDAR_ID. So go back to your .env file and set the new environment variable:

CALENDAR_ID=YOUR_OWN_PUBLIC_CALENDAR_ID

Just a quick note – your CALENDAR_ID will be simply your Google Email address, for example someone@gmail.com. Also don’t forget to make your calendar public, otherwise this example and API setup will not work.

To make your Google Calendar public, you need to adjust the calendar's sharing settings in Google Calendar on a computer. Navigate to the calendar you want to share, then find the "Access permissions for events" section and check the box labeled "Make available to public". You can then choose the level of access you want to grant others.

Here's a step-by-step guide:

• Go to Google Calendar on your computer.

• Find the calendar you want to share under the "My calendars" section on the left side of the screen.

• Click on the three dots (More) next to the calendar name and select "Settings and sharing".

• Under "Access permissions for events," check the box next to "Make available to public".

And for the timeMin and timeMax options I have used the start and end date time we just calculated above.

Now we will get the events array from res.data.items and then map through those events to get the final meetings array. We also need to handle blank array for no events.

const events = res.data.items || [];
const meetings = events.map((event) => {
    const start = event.start.dateTime || event.start.date;
    return `${event.summary} at ${start}`;
});

if (meetings.length > 0) {
    return {
        meetings,
    };
} else {
    return {
        meetings: [],
    };
}

Let’s do some error handling. We will simply push our above event fetching logic inside a try/catch block and handle error inside the catch block. So below is our updated code:

try {
    const res = await calendar.events.list({
        calendarId: process.env.CALENDAR_ID,
        timeMin: start.toISOString(),
        timeMax: end.toISOString(),
        maxResults: 10,
        singleEvents: true,
        orderBy: "startTime",
    });

    const events = res.data.items || [];
    const meetings = events.map((event) => {
        const start = event.start.dateTime || event.start.date;
        return `${event.summary} at ${start}`;
    });

    if (meetings.length > 0) {
        return {
            meetings,
        };
    } else {
        return {
            meetings: [],
        };
    }
} catch (err) {
    return {
        error: err.message,
    };
}

To run the server locally using stdin/stdout, I used the stdioServerTransport() function from the MCP package and passed it to the server's start() method. This part looks like:

const transport = stdioServerTransport();
server.start(transport);

Then I wrapped everything inside an async init() function to avoid top-level await and call the init function.

function init(){
    const transport = stdioServerTransport();
    server.start(transport);
}

init();

6. Final Source Code

So below is the complete code for my server.js file:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import dotenv from "dotenv";
import { google } from "googleapis";
import { z } from "zod";

dotenv.config();

// create the MCP server
const server = new McpServer({
    name: "Sumit's Calendar",
    version: "1.0.0",
});

// tool function
async function getMyCalendarDataByDate(date) {
    const calendar = google.calendar({
        version: "v3",
        auth: process.env.GOOGLE_PUBLIC_API_KEY,
    });

    // Calculate the start and end of the given date (UTC)
    const start = new Date(date);
    start.setUTCHours(0, 0, 0, 0);
    const end = new Date(start);
    end.setUTCDate(end.getUTCDate() + 1);

    try {
        const res = await calendar.events.list({
            calendarId: process.env.CALENDAR_ID,
            timeMin: start.toISOString(),
            timeMax: end.toISOString(),
            maxResults: 10,
            singleEvents: true,
            orderBy: "startTime",
        });

        const events = res.data.items || [];
        const meetings = events.map((event) => {
            const start = event.start.dateTime || event.start.date;
            return `${event.summary} at ${start}`;
        });

        if (meetings.length > 0) {
            return {
                meetings,
            };
        } else {
            return {
                meetings: [],
            };
        }
    } catch (err) {
        return {
            error: err.message,
        };
    }
}

// register the tool to MCP
server.tool(
    "getMyCalendarDataByDate",
    {
        date: z.string().refine((val) => !isNaN(Date.parse(val)), {
            message: "Invalid date format. Please provide a valid date string.",
        }),
    },
    async ({ date }) => {
        return {
            content: [
                {
                    type: "text",
                    text: JSON.stringify(await getMyCalendarDataByDate(date)),
                },
            ],
        };
    }
);

// set transport
async function init() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
}

// call the initialization
init();

Then install the necessary dotenv, googleapis, and zod packages with the below command:

npm install dotenv googleapis zod

Now you can start the server with the command node server.js in your terminal and check whether everything is working properly or not. In case you get any warning to add a type: “module” line inside your package.json file, go ahead and do that. This warning is expected because we are using ES Module syntax for importing our packages instead of default Common JS syntax.

Finally, we are done with the coding part.

7. Connecting with Cursor editor

After setting up the server, I needed to register it inside the Cursor editor:

Start by opening Cursor Settings → Tools & Integrations → New MCP Server.

Inside the object, provide a new object with the below properties according to Cursor Client setup guide mentioned in the Cursor Docs:

• A name: Sumit's Calendar Data

• Command: node

• Arguments: full path to server.js

• Environment variables: API key and Calendar ID

Example:

{
    mcpServers: {
        "sumits-calendar-data": {
            command: "node",
            args: ["/full/path/to/project/server.js"],
            env: {
                GOOGLE_API_KEY: "...",
                CALENDAR_ID: "...",
            },
        },
    },
}

Save and restart Cursor. The tool will now show as active (green).

8. Test Your MCP Server

Now, open the Cursor chat window and type:

"Do I have any meetings today?"

You'll see that:

• It detects the intent

• Chooses the correct MCP tool

• Passes today's date as input

• MCP server returns structured data

• The AI client responds naturally. In my case, I saved an event inside my Google Calendar on today’s date so it returned:

"Yes, you have a meeting with Dr. Chuck at 4:00 PM."

It even works in other languages. If you ask the same question another language other than English, you still get the correct answer. If there are no meetings for a given date, for example if you write:

“Do I have any meeting tomorrow?”

It replies:

"No, you do not have any meetings scheduled for tomorrow."

So now your custom MCP server is fully working, feeding real data from Google Calendar into your AI editor.

This unlocks huge possibilities. Imagine the same approach with GitHub, Notion, internal dashboards, CRMs – anything. It all starts with building and wiring up your MCP server the right way.

Let me know if you would like to build one for your own project! And if this handbook was even a little bit helpful in getting your first MCP server up and running, I’d love to hear about it – it would be great inspiration for me to write more guides like this in the future.

Summary

You can find all the source code from this handbook in this GitHub repository. If it helped you in any way, consider giving it a star to show your support!

Also, if you found the handbook valuable, feel free to share it with others who might benefit from it. I’d really appreciate your thoughts – mention me on X @sumit_analyzen, watch my coding tutorials, or simply connect with me on LinkedIn.