Week 5 — Agent Frameworks & MCP
Sign in
Adventure II · Week 5
Week 5 — Agent Frameworks & MCP
MCP is the USB cable for AI agents. Build a tool once, every agent can use it.

Adventure 8

Recap
Where We Left Off
  • Week 1: What an LLM is — next-word prediction
  • Week 2: Inside it — tokens, attention, transformers
  • Week 3: How to prompt it — sampling + 5 patterns
  • Week 4: Give it tools — the agent loop
  • Week 5 (today): Frameworks + MCP — how the ecosystem actually fits together

Adventure 8

Outcomes
What You'll Know in 3 Hours
By the end of today, you can:
90% of Agent Code
Explain what most agent code actually does — hint: it's plumbing, not the loop
4 Major Frameworks
Name each one and describe when it's the right fit
MCP — the USB for AI
Define it, explain the analogy, and say why the standard matters
Read + Use MCP Servers
Trace source code, add a new server to Claude Code in under 10 minutes
Multi-Agent Patterns
Sketch a multi-agent system AND know when not to build one

Adventure 8

Ground Rules
The Deal — 3 Ground Rules
1
Boring is usually right
Fewer frameworks, fewer agents, fewer abstractions. Resist the urge to over-engineer.
2
Try single-agent first
Multi-agent is rarely the answer. Start simple. Add complexity only when you're stuck.
3
Read source code
MCP servers are 50–200 lines. Read one before you write one. You'll thank yourself.

Adventure 8

Warm-Up
Before We Start — Quick Calibration
Take 2 minutes. Write down your best guesses for these three questions:
Question 1
If you needed your AI assistant to read your Notion notes, what code would you have to write?
Question 2
What does "vendor lock-in" mean in your own words?
Question 3
You've used a USB cable to connect a printer. Why don't AI tools work that way (yet)?

No wrong answers here. These questions frame everything we'll cover today.

Adventure 8

The Plumbing Problem
The Plumbing Problem
Last week you wrote the agent loop in 8 lines. Looked easy.
In real code, the loop is the tip of the iceberg.

Everything below the waterline — state, streaming, errors, retries, permissions, logs, context management — that's the other 90%.

Adventure 8

What 90% of Agent Code Actually Does
The loop is 10% of agent code. The other 90%:
01
Conversation state
Track all messages, tool calls, results — in order
02
Tool registration
Assemble JSON schemas for every tool
03
Tool execution
Parse output, validate args, call function, format result
04
Error handling
Tool fails → format error → decide retry vs surface
05
Context management
Summarize old turns before context window fills
06
Streaming + Logging + Permissions + Multi-turn UX
Push tokens live, record every step, ask before destructive actions, stay responsive

Adventure 8

Why Frameworks Exist
You'd write all 9 of those things yourself — OR use a framework that wrote them for you.
What you get
  • Pre-solved hard problems (state, streaming, errors)
  • Conventions for common patterns
  • A community who hit the same bugs
What you give up
  • Control over the framework's assumptions
  • Easy debugging when something breaks inside the framework
  • Freedom to swap pieces out

Adventure 8

Trade-off — Less Code vs Framework Constraints

Raw API
Framework
Code to write
More
Less
Time to first agent
Hours
Minutes
Debugging your code
Easier
Same
Debugging the framework
N/A
Hard
Flexibility
Total
Constrained
Switching providers
Easier
Often a rewrite
Pick raw for experiments. Pick framework for products.

Adventure 8

📘 Concept Card
Framework
What: A library that handles agent plumbing (state, errors, streaming) so you write less code.
Like: A meal kit — ingredients pre-portioned and washed. Faster to cook, less flexible than from-scratch.
Why it matters: Most "agent code" is plumbing. Frameworks save the 90%. They cost you flexibility on the 10%.

✓ Takeaway: A framework is a trade — you trade control for speed. Know what you're trading.

Adventure 8

Frameworks
The 4 Frameworks You Should Know
  • LangChain — the giant, biggest ecosystem
  • OpenAI Assistants API — hosted, easiest start, OpenAI-locked
  • CrewAI — multi-agent focused
  • Claude Agent SDK — MCP-native, clean
Each has a sweet spot. Let's go through them.

Adventure 8

LangChain — The Giant
Strengths
  • Started late 2022 — massive ecosystem
  • Document loaders for every file type
  • Retrieval pipelines, dozens of tool implementations
  • Whatever you want, someone has an example
Weaknesses
  • Heavy abstractions
  • You'll debug the framework as much as your code
  • API has changed a lot over time
Use it when
Building something complex (RAG, multi-step research) and you want to start from working examples.

Adventure 8

OpenAI Assistants API — Easy Start, Locked In
Strengths
  • Easiest way to start — no plumbing
  • Built-in conversation persistence
  • Code interpreter + file search out of the box
Weaknesses
  • Locked to OpenAI models
  • Switching to Claude later = full rewrite
Use it when
Quick prototype on OpenAI and you don't care about portability.

Adventure 8

CrewAI — Multi-Agent Focused
Strengths
  • Clean primitives for specialized agent roles
  • "This agent researches, that one writes, that one edits"
  • Built-in coordination patterns
Weaknesses
  • Multi-agent is fragile
  • Lots of orchestration overhead
  • A single well-prompted agent often works better
Use it when
You genuinely need parallel specialized roles AND you've already tried single-agent first.

Adventure 8

Claude Agent SDK — MCP-Native
Strengths
  • Simple and direct — minimal abstractions
  • Plugs into the MCP ecosystem natively
  • Excellent docs, same primitives Claude Code is built on
Weaknesses
  • Newer — smaller ecosystem than LangChain
  • Optimized for Claude specifically
Use it when
Building on Claude and you want clean MCP integration without LangChain's abstractions.

Adventure 8

Decision Tree
The Framework Decision Tree
Do you NEED multiple specialized agents?

├── Yes → CrewAI

└── No (single agent is fine):

    │

    Locked to one model provider?

    ├── OpenAI only → OpenAI Assistants

    ├── Claude only → Claude Agent SDK

    └── Want to switch / try many

              → LangChain (or raw API)

Adventure 8

Knowledge Check 1
Pick a Framework
For each scenario, predict which framework you'd reach for — and why:
Scenario 1
"Build a homework helper using Claude. Just one agent."
Scenario 2
"Prototype a customer support assistant on OpenAI in one day."
Scenario 3
"Build a complex research tool that uses 3 different LLMs."
Scenario 4
"Build a 'company-in-a-box' with separate Manager, Engineer, and QA agents."

Write your answers before looking at the decision tree. Then check yourself.

Adventure 8

The Boring Truth — Most Apps Need No Framework
Most beginners over-engineer. Here's what actually works:
For your first 5 agents
  • Use the raw API
  • Use a single agent
  • Use a strong system prompt
When to add a framework
Only when you hit a real limit you can't solve by improving your prompt or restructuring your code.

✓ Takeaway: Frameworks are a tool, not a starting point. Earn the complexity.

Adventure 8

The MCP Problem
The Problem MCP Solves
Imagine you build a "read GitHub issues" tool and wire it into Claude Code. Works great.
Want it in Cursor?
Different format. Rewrite.
Want it in ChatGPT?
Different format. Rewrite.
Want it in LangChain?
Different format. Rewrite.
Same tool. 4 implementations. Multiply by every tool, every product, every developer — that's billions of dollars of duplicated work.

Adventure 8

MCP — Model Context Protocol
MCP is the standard that fixes this.
Published by
Anthropic, late 2024
The idea
Describe a tool once, in MCP format. Any MCP-compatible agent can use it.
Already adopted by
Claude Code, Cursor, OpenAI, and many more

Adventure 8

The USB Analogy
The USB Analogy
Before USB
  • Every printer had its own port and cable
  • Adding a printer = new drivers, sometimes new hardware
  • Every peripheral company made their own everything
After USB
  • One port — plug anything in
  • The ecosystem exploded
MCP is doing this for AI tools.

Adventure 8

📘 Concept Card
MCP — Model Context Protocol
What: An open protocol where tools are described in a standard way, so any compatible agent can use any compatible tool.
Like: USB. A printer maker doesn't write a custom port for every computer — they implement USB once, and every USB computer works.
Why it matters: Build a tool once, every MCP agent gets it. The whole ecosystem grows much faster.

✓ Takeaway: MCP is a standard, not a product. Standards change industries.

Adventure 8

Who Built It, Who Uses It
Published by
Anthropic (late 2024)
Adopted by (so far)
  • Claude Desktop, Claude Code
  • Cursor
  • OpenAI (announced support)
  • Replit, Zed, and dozens more
  • Community: hundreds of MCP servers on GitHub
The fastest standard adoption in AI history.

Adventure 8

MCP Anatomy
What an MCP Server Does — 3 Jobs
An MCP server is a small program that exposes tools to agents. It does exactly three things:
1
Announce
When an agent connects, list the tools it provides and their schemas
2
Execute
When an agent calls a tool, run the actual function
3
Return
Give the result back in standard MCP format
That's it. Most MCP servers are 50–200 lines of code.

Adventure 8

Trivial Example — Random Number Server
A complete MCP server that exposes one tool:
@server.tool()

def get_random_number(min: int, max: int) -> int:

    """Return a random integer between min and max (inclusive)."""

    return random.randint(min, max)
That's the whole server. Now ANY MCP-compatible agent can:
  • Connect to it
  • See get_random_number in its tool list
  • Call it whenever it needs a random number

You didn't write any agent code. You wrote one function. The MCP protocol does the rest.

Adventure 8

Look Inside a Real MCP Server
The filesystem MCP server lets agents read/write files in a folder you specify.
Source code
~150 lines total. No magic.
Tools it exposes
  • read_file(path)
  • write_file(path, content)
  • list_directory(path)
  • search_files(pattern)
Each tool is
  • A @server.tool() decorator
  • A 1-line description
  • 5–20 lines of implementation

Find it on GitHub: modelcontextprotocol/servers — read it tonight.

Adventure 8

Build Your Own in 50 Lines
The pattern is the same every time:
01
Pick an SDK
Python or TypeScript — both have official MCP SDKs
02
Define your tools
Write your functions with @server.tool() decorators
03
Run the server
stdio transport (simplest) or HTTP
04
Add to any MCP client
Drop the config snippet into Claude Code, Cursor, or any MCP client
The hardest part is deciding what tools to expose. The code itself is trivial.

Adventure 8

Knowledge Check 2
What Would MCP Solve Here?
For each scenario, predict: would MCP help, and why?
Scenario 1
"I want Claude Code to read my Notion workspace."
Scenario 2
"I want my own Python script to talk to Claude."
Scenario 3
"I want to use the same read_email tool in both Cursor and Claude Code."
Scenario 4
"I want to switch from Claude to GPT for my chatbot."

Adventure 8

📘 Concept Card
MCP Server
What: A small program that exposes tools to MCP-compatible agents — announce, execute, return.
Like: A USB peripheral. A printer doesn't care what computer plugs in; it just speaks USB. MCP servers speak MCP.
Why it matters: Building a server is trivial; the value is plug-and-play. Write once, every agent uses it.

✓ Takeaway: You now know enough to read any MCP server's source code and understand exactly what it does.

Adventure 8

Real MCP Servers
Real MCP Servers You Can Plug In Today
filesystem
Read/write/list files in a folder
github
Read repos, issues, PRs; comment on issues
postgres
Run SQL queries against a database
slack
Read channels, post messages, search
puppeteer
Drive a real browser — navigate, click, screenshot
memory
Persistent key-value memory across sessions
fetch
HTTP GET any URL, returns clean text
gmail
Read inbox, search threads, draft emails
notion
Read/write Notion pages and databases

Adventure 8

Plug In a New One in 3 Steps
1
Find the config snippet
Most MCP servers have a copy-paste block right in their README
2
Add it to your config
Paste into ~/.claude/mcp_settings.json or via the Claude Code UI
3
Restart Claude Code
The new tools just appear in Claude's tool list. No code changes. No rebuild.

Adventure 8

Hands-On
Hands-On — Add a Real MCP Server
We'll add the memory MCP server (persistent notes across sessions) to Claude Code. Together, step by step:
01
Find the official config snippet
Open the modelcontextprotocol/servers repo and find the memory server README
02
Paste into your MCP config
Add the JSON block to ~/.claude/mcp_settings.json
03
Restart Claude Code
Close and reopen — the server starts automatically
04
Watch the new tools appear
Claude's tool list grows. No rebuild needed.
05
Use them live
Try: "Claude, remember that my favorite color is blue." Then close and reopen. Ask again.

Adventure 8

The New Tools Appear
After restart, Claude Code's tool list grows. You can now ask:
"Remember that…"
→ memory.set()
"What did I tell you last week?"
→ memory.get()
"Forget about X"
→ memory.delete()

You didn't write a single line of agent code. The MCP server provided everything.

Adventure 8

Multi-Agent
When 1 Agent Isn't Enough
Three multi-agent patterns are worth knowing:
1
Orchestrator + Workers
One agent delegates, others specialize
2
Debate
Two agents argue opposite sides, a third judges
3
Hierarchical
Managers and individual contributors, recursive delegation

But first: most "multi-agent" projects would work better as one well-prompted agent. Apply these patterns only after you've exhausted single-agent approaches.

Adventure 8

Pattern 1 — Orchestrator + Workers
     User: "Plan my friend's birthday"

                    │

               Orchestrator

             ╱      │      ╲

    Researcher  Planner   Budgeter

             ╲      │      ╱

               Orchestrator

                    │

               Final answer
Orchestrator delegates. Workers focus. Mirrors how teams actually work.

Adventure 8

Pattern 2 — Debate
Two agents given opposing perspectives. A third reads the argument and decides.
Useful for: spotting weak arguments, exploring trade-offs, reducing single-agent bias.

Adventure 8

When Multi-Agent Is Wrong
Most multi-agent demos would work better as a single agent with a longer system prompt.
Multi-agent adds
  • More tokens (each agent has its own context)
  • More latency (steps run in sequence)
  • More fragility (one broken agent breaks the whole flow)
The rule
Try single-agent first. Bring in multi-agent only when you genuinely can't get one agent to do the job, no matter how you prompt it.

✓ Takeaway: Multi-agent is a power tool, not a starting point.

Adventure 8

Summary
The 3-Hour Summary
You now understand:
Frameworks exist because of plumbing
90% of agent code is state, errors, streaming — not the loop itself
4 frameworks, each with a sweet spot
LangChain, OpenAI Assistants, CrewAI, Claude Agent SDK
MCP is the USB-for-AI standard
Write a tool once — every MCP-compatible agent can use it
MCP servers are 50–200 lines
You could write one tonight. You read one today.
Multi-agent patterns exist — most projects don't need them
Orchestrator + Workers, Debate, Hierarchical. Single-agent first, always.

Adventure 8

Reference
Glossary
Framework
Library handling agent plumbing (state, errors, streaming) so you write less code
MCP (Model Context Protocol)
Open protocol where tools are described once and used by any compatible agent
MCP server
Small program exposing tools over MCP — announce, execute, return
MCP client
The agent side — connects to MCP servers and uses their tools
Orchestrator
Agent whose job is to delegate work to other specialized agents
Multi-agent system
Multiple agents working together, each with a different role
Vendor lock-in
Code so tied to one provider that switching to another is a full rewrite

Adventure 8

Week 6 Preview
This Week's Mission + Week 6 Preview
This week — your mission
  • Add one new MCP server to your Claude Code and use it for a real task
  • Read the source of one MCP server you didn't write — it's only ~100 lines
Next week — Build Your Real Product
You now know: what an LLM is, how it works, how to prompt it, how to give it tools, how to build on standards.
Next week you put it all together and ship something other people can actually use. PRD, wireframe, spike, deploy.
Bring a problem you wish someone would build a tool for. It's about to be yours.

Adventure 8