Disclaimer

• For learning & research only.
• Not investment or legal advice.
• Code is simplified — use at your own risk.

Kha Do · FIT-HCMUS · [email protected] — inspired by Stanford CS146S "The Modern Software Developer".

What we'll cover

Last session, in one slide

We built a coding agent in ~80 lines of Node.js:

It had three hard-coded tools: read_file · write_file · run_command.

Now we want GitHub, databases, Slack, a browser, docs… Do we hand-write every tool?

The M × N integration problem

Every AI app re-implements the same integrations, each in its own way:

Every new app rebuilds the same connectors; every new tool must court every app.

What is MCP?

Shipping a product? Ship its MCP server too

Whatever system you build next, your users' agents are users now — don't make humans hand-wrap your API.

The product checklist grew: API · docs · SDK · MCP server. GitHub, Notion, Stripe, Sentry already ship theirs — "we have an API" is no longer the finish line.

Architecture — host, client, server

What a server offers — three things

Rule of thumb: tools ≈ POST (do something) · resources ≈ GET (read something) · prompts ≈ saved recipes.

Under the hood — a session on the wire

Plain JSON-RPC 2.0 messages. First a handshake, then requests:

Same shape for resources/list · resources/read · prompts/list · prompts/get.

Two transports — local and remote

⚠️ Gotcha: on stdio, stdout belongs to the protocol — one stray console.log() corrupts the stream. Log with console.error().

Where MCP fits in the agent loop

The model never knows MCP exists — it just sees a longer tool list. Your loop is unchanged; only the dispatch changes.

What it feels like

No custom glue: the GitHub team wrote the server once; MCP-compatible hosts can reuse it.

Servers worth knowing

Treat community servers like npm packages: check the author before installing.

Plug one into Claude Code

# local stdio server (our todo server, later)
claude mcp add todo -- node server.js

# remote HTTP server (GitHub official)
claude mcp add --transport http github \
  https://api.githubcopilot.com/mcp/

# inspect
claude mcp list
claude mcp get github

{
  "mcpServers": {
    "todo": {
      "command": "node",
      "args": ["server.js"]
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Scopes: local (just you, this project) · project (.mcp.json, shared with the team) · user (all your projects). In-app: /mcp shows status & login.

One server, many hosts

Because it's a standard, more hosts can reuse the same connector:

Write your server once tonight → reuse it wherever the host supports that transport/auth.

⚠️ New powers, new risks

Guardrails: install from trusted sources · least-privilege tokens (read-only when possible) · keep approval prompts on for writes & shell · review what each server exposes with /mcp.

What we're about to build

~60 lines of Node.js: tools to act, a resource to read, a prompt to reuse.

Step 0 — Project setup

mkdir todo-mcp && cd todo-mcp
npm init -y
npm pkg set type=module          # enable ES modules (import/export)

npm install @modelcontextprotocol/sdk zod

Requires Node 20+. @modelcontextprotocol/sdk is the SDK package used in this demo; zod declares each tool's input schema.

Step 1 — A server with one tool

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

const server = new McpServer({ name: "todo", version: "1.0.0" });
const tasks = [];                              // in-memory state

server.registerTool(
  "add_task",
  {
    description: "Add a task to the todo list",
    inputSchema: { text: z.string() },         // the model sees this schema
  },
  async ({ text }) => {
    tasks.push({ id: tasks.length + 1, text, done: false });
    return { content: [{ type: "text", text: `Added #${tasks.length}: ${text}` }] };
  }
);

await server.connect(new StdioServerTransport());   // serve over stdin/stdout
console.error("todo server ready");                 // stderr, NOT stdout!

That's a complete demo server: name + version, one tool, stdio transport.

Step 2 — Two more tools

server.registerTool(
  "list_tasks",
  { description: "List all tasks with their status", inputSchema: {} },
  async () => ({
    content: [{
      type: "text",
      text: tasks.length
        ? tasks.map(t => `${t.id} ${t.done ? "✅" : "⬜"} ${t.text}`).join("\n")
        : "No tasks yet.",
    }],
  })
);

server.registerTool(
  "complete_task",
  { description: "Mark a task as done", inputSchema: { id: z.number() } },
  async ({ id }) => {
    const t = tasks.find(t => t.id === id);
    if (!t) return { content: [{ type: "text", text: `No task #${id}` }], isError: true };
    t.done = true;
    return { content: [{ type: "text", text: `Completed #${id}: ${t.text}` }] };
  }
);

Return isError: true for failures — the model reads it and can recover, just like the self-correction loop from session 1.

Step 3 — A resource and a prompt

server.registerResource(
  "todo-list",
  "todo://list",
  {
    description: "The current todo list",
    mimeType: "text/plain",
  },
  async (uri) => ({
    contents: [{
      uri: uri.href,
      text: tasks
        .map(t => `${t.done ? "x" : " "} ${t.text}`)
        .join("\n"),
    }],
  })
);

server.registerPrompt(
  "plan_my_day",
  {
    description: "Plan the day from open tasks",
    argsSchema: {},
  },
  () => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: "Read my todo list and propose " +
              "a realistic plan for today.",
      },
    }],
  })
);

In Claude Code the prompt appears as /todo:plan_my_day; the resource can be attached with @todo:todo://list.

Step 4 — Test it with the Inspector

npx @modelcontextprotocol/inspector node server.js
# 🔗 opens http://localhost:6274 in your browser

Debug your server here first — with a UI and raw messages — before involving an LLM. Two moving parts are easier than three.

Step 5 — Plug it into Claude Code 🎬

claude mcp add todo -- node server.js
claude          # start a session — then try it:

Same trace shape as session 1 — but the tools now come from your server, not the agent's source code.

Step 6 — Make your agent an MCP host

The mini-agent from session 1 can load servers too — the SDK has a client side:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const mcp = new Client({ name: "mini-agent", version: "1.0.0" });
await mcp.connect(new StdioClientTransport({ command: "node", args: ["server.js"] }));

// 1 · merge MCP tools into the tool list from session 1
const { tools: mcpTools } = await mcp.listTools();
const tools = [...localTools, ...mcpTools.map(t => ({
  type: "function",
  function: { name: t.name, description: t.description, parameters: t.inputSchema },
}))];

// 2 · in the agent loop, dispatch to the server when it's an MCP tool
for (const call of reply.tool_calls) {
  const args = JSON.parse(call.function.arguments);
  const result = mcpTools.some(t => t.name === call.function.name)
    ? await mcp.callTool({ name: call.function.name, arguments: args })  // → MCP server
    : await handlers[call.function.name](args);                          // → local tool
  messages.push({ role: "tool", tool_call_id: call.id,
                  content: JSON.stringify(result) });
}

The loop is untouched — only the tool list and the dispatch grew. Your agent is now a host.

Step 7 — Same server, over HTTP 🎬

// http.js — Steps 1–3 unchanged, only the plug differs   (npm install express)
import express from "express";
import { StreamableHTTPServerTransport }
  from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { makeServer } from "./server.js";   // wrap the registerTool/Resource/Prompt code in a function

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

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,          // stateless — simplest mode: no sessions to track
  });
  res.on("close", () => transport.close());
  await makeServer().connect(transport);    // fresh server instance per request
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000);                           // → POST http://localhost:3000/mcp

claude mcp add --transport http todo http://localhost:3000/mcp   # host = Claude Code
npx @modelcontextprotocol/inspector          # or Inspector → transport: Streamable HTTP

Same tools, resource, prompt — only the transport changed. But the host no longer owns the process: your server is now a web service anything that can reach port 3000 can call…

Going public? Then auth is not optional

Open MCP endpoint = open tools endpoint. Public means authenticate every request.

The OAuth 2.1 dance, in one picture

①–④ happen once per server — after that every call is just ⑤→⑥ with a cached token (auto-refreshed). Your server never sees a password.

The API-key guard — 10 lines of Express

// in http.js, BEFORE the /mcp route — bad requests never reach the MCP transport
const KEY = process.env.MCP_KEY;              // generate once: openssl rand -hex 32

app.use("/mcp", (req, res, next) => {
  const token = (req.headers.authorization ?? "").replace("Bearer ", "");
  if (token !== KEY) {
    return res
      .status(401)                            // the same "door" the OAuth dance knocks on
      .set("WWW-Authenticate", "Bearer")
      .json({ error: "unauthorized" });
  }
  next();                                     // key OK → on to the MCP transport
});

# every client just sends the key as a header
claude mcp add --transport http todo https://todo.example.com/mcp \
  --header "Authorization: Bearer $MCP_KEY"

Upgrading to OAuth later swaps this key check for token validation behind the same 401 door — clients don't change.

Real servers — where does the auth live?

Same dance at Notion · Sentry · Linear · Atlassian: claude mcp add --transport http … → browser pops. And GitHub's server also takes a PAT via --header — that's our level-1 key, offered by a real server.

Works offline too — Ollama & FIT

⚠️ Small models get confused by big tool lists. Connect one or two servers, not ten — curate what the model sees.

Honest limits

Same rule as session 1: a few sharp tools beat many fuzzy ones — MCP makes adding tools easy, curating them is your job.

The missing piece — know-how

MCP gives reach. Skills give repeatable process.

MCP = can do · Skills = should do.

Anatomy of a skill

.claude/skills/
└── daily-standup/
    ├── SKILL.md        ← required
    ├── template.md     ← optional extras
    └── scripts/
        └── fetch_ci.sh

---
name: daily-standup
description: Write my morning standup update.
  Use when I ask for a standup, a daily plan,
  or "what's on today".
---

# Daily standup

1. Call `todo · list_tasks`; collect open tasks.
2. Call `github · list_issues` assigned to me,
   updated in the last 24 h.
3. Write three sections:
   **Done · Today · Blockers** (see template.md).
4. Under 10 lines. Bullets. No fluff.

Note steps 1–2: the skill orchestrates the MCP tools from Part 3 — capabilities and know-how compose.

A skill in action 🎬

One vague ask — the skill supplies the process, MCP supplies the reach:

Without the skill: a different format every morning. With it: same process, every time, for everyone who has the folder.

Same trick for building software 🎬

Encode your team's dev process — plan → code → review → test — and every feature ships the same way:

---
name: feature-dev
description: Build a feature end-to-end.
  Use when asked to add or change
  functionality in this repo.
---

# Feature workflow

1. **Plan** — restate the ask; list the
   files you'll touch, then proceed.
2. **Code** — smallest diff that works;
   follow STYLE.md.
3. **Review** — self-review the diff:
   naming, edge cases, dead code.
4. **Test** — run `npm test`; fix
   failures before saying "done".

The skill defines what "done" means: no review skipped, no red tests — the agent's standard becomes the team's standard.

Why skills are cheap — progressive disclosure

A skill has low standing cost until the moment it's needed:

Contrast with Part 3's Honest limits: tool schemas cost attention; skills load detail on demand.

Write your first skill — tonight

mkdir -p .claude/skills/daily-standup

$EDITOR .claude/skills/daily-standup/SKILL.md

claude
# "standup time"  or  /daily-standup

Free skill packs worth installing

⚠️ A skill is instructions your agent will follow — read SKILL.md before installing. Same supply-chain rule as MCP servers: trust the author.

Where does know-how live?

Three homes for what your agent "knows" — pick by how often it's needed:

Rule of thumb: needed every turn → CLAUDE.md · needed for some tasks → a skill · needs to act on something → MCP.

MCP × Skills — better together

Reach without know-how is chaos. Know-how without reach is advice.

Recap — the mental model

• 🔍Problem: M apps × N tools = M×N custom glue.
• 🔌MCP = one open protocol → M + N connectors. "USB-C for AI."
• 🏠Host ⊃ clients (1:1) → servers — over stdio or HTTP, speaking JSON-RPC.
• 🎁Servers offer tools (act) · resources (read) · prompts (reuse).
• 🧠The model never sees MCP — just a longer tool list; the loop is unchanged.
• 🛠️~60 lines of Node.js = a real server reusable across MCP-compatible hosts.
• 📖Skills = folders of instructions — know-how that orchestrates tools with low standing context cost.

Where to go next

You have the mental model. Try three things tonight:

📝 Homework — what to build

{
  "model": "qwen3.5:4b",
  "baseURL": "http://localhost:11434/v1",
  "mcpServers": {
    "todo":      { "command": "node", "args": ["server.js"] },
    "todo-http": { "url": "https://you.onrender.com/mcp",
                   "headers": { "Authorization": "Bearer …" } }
  }
}

📝 Homework — submit & grading

References & resources

MCP evolves fast — spec revisions & server URLs change; verify on official docs before class.