Build Your First MCP Server

SUTD AI · Agentic Engineering Workshop · Model Context Protocol

A three-hour, hands-on session. You will learn what the Model Context Protocol is, why it exists and where it fits, then write your own MCP server in Python that gives an AI agent (AWS Kiro) the ability to read and write your notes — and connect that same agent to a shared design-thinking board.

What you will walk out with

1. A working MCP server, written by you, that exposes a folder of Markdown notes (the sample vault/, or your own Obsidian vault) to any MCP client.

2. Kiro configured on your laptop with your server, plus one or two third-party MCP servers added by URL.

3. A clear mental model of what MCP is, when to reach for it, and when not to.

No prior MCP knowledge is assumed. If you can read a short Python function you can do the hands-on part; the file operations are already written, you write the MCP layer.

Related MCP server: obsidian_mcp

The session at a glance

Full minute-by-minute plan for facilitators: docs/facilitator-runbook.md.

Before you arrive (15 minutes)

Do the pre-work so the session is spent building, not installing: docs/00-prework.md. In short: install Kiro and sign in, install uv, get this repo, run uv sync, then uv run check_env.py until everything is green.

Repository map

server.py            ← YOU edit this. The MCP server, with STEP 1–4 marked as TODOs.
notes.py             ← done for you: read/search/create/append Markdown notes (macOS/Windows/Linux)
check_server.py      ← talks to your server exactly like Kiro does, and shows the messages
check_env.py         ← pre-work check
setup_kiro.py        ← writes .kiro/settings/mcp.json with the absolute paths Kiro needs
vault/               ← sample notes so everything works out of the box
solution/server.py   ← the finished server, for comparison
.kiro/               ← workspace MCP config template + a steering file so Kiro can coach you
docs/                ← the curriculum (read in order)

The curriculum

Quick start (if you already did the pre-work)

uv sync                      # installs the MCP SDK into .venv
uv run check_env.py          # everything green?
uv run setup_kiro.py         # writes the Kiro config with absolute paths
uv run check_server.py       # "complete STEP 1 first" — that is your cue to open server.py

Open this folder in Kiro, then follow docs/02-build-notes-mcp.md.

Using your own notes

The server reads whatever folder NOTES_VAULT points at. To use an Obsidian vault:

uv run setup_kiro.py --vault "/Users/you/Documents/My Vault"       # macOS
uv run setup_kiro.py --vault "C:/Users/you/Documents/My Vault"      # Windows

Any folder of .md files works; nothing Obsidian-specific is required.

Credits

Built by SUTD AI for the Agentic Engineering Workshop series. The design-thinking board used in the final segment is design-think-agent. Code is MIT; documentation is CC BY 4.0.