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

Your users' agents are users now.

Architecture — host, client, server

What a server offers — three things

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

Design sharp tools

MCP gives the plug. Tool design decides whether the agent uses it well.

A few sharp tools beat one giant magic tool.

Quick check — tool or resource?

Ask: does the model act, or does the app read context?

Side effects? Usually a tool. Read-only context? Usually a resource.

Bad tool → good tools

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

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.

Permission ladder

Higher impact → stronger human confirmation.

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.

Debug from the bottom up

Do not start by blaming the model.

Two moving parts first. Then 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.

How your agent becomes a host

A host does three jobs: plug in servers, show tools to the model, then route each call.

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.

Public server = front door on the internet

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.

Grab the demo code — three variants

Same todo server, three homes — the state story in runnable code:

The two HTTP variants also expose a REST API (/api/tasks) beside /mcp — same state, two doors: REST for humans & scripts, MCP for models. Bonus: market-mcp — a stdio server wrapping a real finance API (gold · FX): ask "giá vàng SJC hôm nay?" and watch the cutoff problem disappear.

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.

For coding: skills remember team rules

The user says “add feature”. The skill says “do it our way”.

Example: team rules inside SKILL.md

These are the tiny conventions humans forget to repeat.

Same trick: one feature request → PR-ready

The skill fills in the branch, review, tests, and PR checklist.

---
name: feature-dev
description: Build a feature using our PR rules.
  Use when asked to add or change functionality.
---

# Team conventions

1. Create branch: feat/<ticket>-slug
2. Keep diff small
3. Self-review before final
4. Run unit tests
5. Open PR with test evidence

The user did not ask for branch names, review convention, or tests. The skill remembered.

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

Read SKILL.md before installing. Your agent will follow it.

What comes built in?

Different agent surfaces package the same idea: reusable know-how.

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.

Skills in your agent — the flow

One request, end to end. Loading a skill is just another tool call:

---
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 the `todo` server's `list_tasks` tool to collect tasks.
2. Write three sections: **Done · Today · Blockers**.
3. Under 10 lines. Bullets. No fluff.

Steps 2–4 are progressive disclosure flowing through the session-1 tool loop. Code next ↓

Build it yourself — skills in your agent

No protocol needed — your agent already has a file reader and a loop:

// 1 · discover at startup: scan skills/*/SKILL.md — keep ONLY the frontmatter
const skills = loadSkillIndex("./skills");     // → [{ name, description, path }]

// 2 · advertise cheaply: one line per skill in the system prompt
const SYSTEM = `You are a coding agent. Use tools to finish the task.
Available skills:
${skills.map(s => `- ${s.name}: ${s.description}`).join("\n")}
If a request matches a skill, call use_skill FIRST, then follow its steps.`;

// 3 · load on demand: ONE new tool — the agent loop is untouched
tools.push({ name: "use_skill",
             description: "Load a skill's instructions by name",
             parameters: { name: "string" } });
handlers.use_skill = async ({ name }) =>
  fs.readFile(skills.find(s => s.name === name).path, "utf8");

// 4 · bundled templates & scripts? read_file / run_command already handle it 🎉

The previous slide's flow, in ~20 lines. Progressive disclosure through the tool loop you built in session 1.

Recap — the mental model

Capabilities need design. Reach needs trust. Know-how needs skills.

Where to go next

You have the mental model. Try three things tonight:

📝 Homework — what to build

📝 Homework — submit & grading

References & resources

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