MCP Workshop

A hands-on introduction to the Model Context Protocol in Python. Ninety minutes to two hours, laptop open the whole time.

By the end you will have built an MCP server, written a complete agent loop by hand, rebuilt it in ten lines with a framework, and put the result in a browser — all running locally on a free model, with the wifi off if you like.

Written against MCP revision 2026-07-28 and Python SDK mcp 2.0. Both are recent, and both broke things. Most MCP material online predates them; this workshop calls out the differences as it goes.

---

Why this exists

Everyone is building integrations between language models and their own systems, and everyone is building them slightly differently. MCP is the attempt to stop that — one protocol, so a tool written once works with any model, in any host application, in any language.

The idea is not complicated. The confusing part right now is that the protocol went through its largest revision to date in July 2026, the Python SDK shipped a breaking 2.0 at the same time, and most tutorials you will find were written before both. So this workshop teaches the current thing and points out where the older material diverges.

It also deliberately makes you write the agent loop by hand before handing you a framework — because the loop is about forty lines, and understanding it is the difference between debugging your agent and guessing at it.

Who it's for

Python developers who have used an LLM API before. You do not need prior MCP experience, agent-framework experience, or any model credentials.

You do need a laptop with Python 3.10+ and roughly 4 GB free for a local model.

What you'll walk away with

• A mental model of MCP that survives contact with a real codebase
• A working server you can extend into something you actually use
• The agent loop, written by your own hands — no longer a black box
• An informed opinion on when a framework is worth it
• A clear-eyed view of the security problems, which are not the usual ones

---

Start here

git clone https://github.com/GlobalAICommunity/mcp-workshop.git
cd mcp-workshop
make setup
make check

Do this before the session — it downloads a few hundred MB. Full instructions, including picking a model: docs/01-get-started.md.

---

The workshop

	Module	Time
1	Get Started	5 min	Pre-work check
2	MCP basics	25 min	Concepts, architecture, and what changed in 2026-07-28
3	Build a server	30 min	Tools, structured output, resources, prompts
4	A client, and an agent loop	25 min	A raw client, then the whole agent loop by hand
5	Put the agent in a browser	20 min	Reuse the handwritten loop behind a chat UI
6	Where next	10 min	Remote servers, security, what to build

Reference: cheatsheet · glossary · models · troubleshooting

Teaching this yourself? docs/facilitator.md has timings with minimums, per-module teaching notes, the questions people always ask, and what to do when the demo breaks.

Running short? The resource and prompt in module 3, the Inspector step, and module 6 can each be demoed rather than typed — that brings it back to ~90 min.

---

What you build

A fake travel service — weather, forecasts and flights. Fake on purpose: no API keys, no network, and the same answer every time, which matters when you are demoing in front of a room.

flowchart LR
    U["you"] --> W["web UI<br/>module 5"]
    W --> A["agent"]
    A <--> M["model<br/>ollama / gemini / grok / foundry"]
    A <-->|MCP over stdio| S["travel server<br/>module 3"]
    S --> T["get_weather · get_forecast<br/>search_flights · list_destinations"]

Loading

The Global AI Learn course creates each application file from scratch under src/starter/, one runnable section at a time. src/solution/ contains the finished reference implementations.

---

Models

You need something that can call tools. The default is Ollama running qwen3:4b locally: free, no account, works offline — and verified end to end for this workshop, including multi-step tool chains.

Can't run a local model? Google Gemini, xAI Grok and Microsoft Foundry are one-line swaps in .env. See docs/models.md.

MCP_WORKSHOP_PROVIDER=ollama   # ollama | google | grok | foundry

---

Repo layout

global-ai-learn/  the Global AI Learn course
docs/             supporting workshop and reference material
src/
  solution/       the finished reference implementations
  model_config.py shared model-provider configuration
scripts/
  verify_setup.py      make check
  raw_jsonrpc.sh       poke the server with no SDK at all

One virtualenv, .venv, runs the official MCP 2 server, raw client, handwritten agent loop, and browser app. Module 5 reuses the same loop behind a Starlette HTTP interface.

---

Licence

MIT. Use it, fork it, run it at your own event.