Model Context Protocol

---

📚 Useful Resources

MCP (Model Context Protocol)

• MCP Official Docs — Spec, tutorials, and guides
• MCP-UI — Official standard for interactive UI in MCP
• MCP Auth Guide (Auth0) — Deep dive into MCP auth spec updates

A2A (Agent-to-Agent Protocol)

• A2A Official Docs — Spec and guides
• A2A GitHub Repo — Protocol spec and implementations
• Announcing A2A (Google Blog) — Protocol vision and motivation

MCP vs A2A

• A2A and MCP (Official) — How they complement each other

---

Running the MCP Server

1. Install dependencies

uv sync

2. Set up environment variables

Copy the example env file and fill in your OpenAI API key:

cp .env.example .env

3. Run the MCP server locally

uv run server.py

The server will start on http://localhost:8000.

4. Expose the server with ngrok (for remote/Claude Desktop access)

ngrok creates a public URL that tunnels to your local server. This is required for Claude Desktop and remote MCP clients.

4a. Create an ngrok account

1. Sign up at https://dashboard.ngrok.com/signup
2. Copy your authtoken from https://dashboard.ngrok.com/get-started/your-authtoken

4b. Install ngrok

Option A — apt (requires sudo):

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt-get update && sudo apt-get install -y ngrok

Option B — direct download (no sudo, recommended for WSL2):

mkdir -p ~/.local/bin
curl -sSL https://bin.equinox.io/c/bNyj1mQVY4c/ngrok-v3-stable-linux-amd64.tgz \
  | tar xz -C ~/.local/bin
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Warning: Do NOT use snap install ngrok on WSL2 — snap does not work reliably in WSL.

4c. Configure authtoken

ngrok config add-authtoken <YOUR_TOKEN>

4d. Start the tunnel

In a separate terminal:

ngrok http 8000

Note the Forwarding URL (e.g. https://xxxx.ngrok-free.app).

4e. Restart the MCP server with ISSUER_URL

ISSUER_URL=https://xxxx.ngrok-free.app uv run server.py

Important: The ISSUER_URL must match the ngrok forwarding URL exactly, or OAuth authentication will fail.

4f. Connect Claude Code (.mcp.json)

Create a .mcp.json file in the project root:

{
  "mcpServers": {
    "cat-shop": {
      "type": "streamable-http",
      "url": "https://xxxx.ngrok-free.app/mcp"
    }
  }
}

Replace xxxx.ngrok-free.app with your actual ngrok URL.

4g. Connect Claude Desktop

Add the following to your Claude Desktop MCP config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "cat-shop": {
      "type": "streamable-http",
      "url": "https://xxxx.ngrok-free.app/mcp"
    }
  }
}

4h. Verify the server is reachable

curl -s -X POST https://xxxx.ngrok-free.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

A 401 response (authentication required) means the server is reachable and OAuth is working.

4i. Troubleshooting

Problem	Solution
ngrok: command not found	PATH issue — run export PATH="$HOME/.local/bin:$PATH"
ERR_NGROK_* errors	Authtoken not configured — run ngrok config add-authtoken <TOKEN>
OAuth failures after connecting client	ISSUER_URL doesn't match the current ngrok URL
Free tier: URL changes on every restart	Must update ISSUER_URL, .mcp.json, and Claude Desktop config each time you restart ngrok

---

Build 🏗️

In today's assignment, we'll be building an MCP server with OAuth authentication — a cat shop application that exposes tools for browsing products, managing a cart, and checking out.

• 🤝 Breakout Room #1

  • Set up the MCP server with OAuth and the product database
  • Explore the MCP tools: list_products, get_product, add_to_cart, view_cart, remove_from_cart, checkout

• 🤝 Breakout Room #2

  • Connect an MCP client to the server
  • Build an end-to-end interaction flow using the MCP tools

Ship 🚢

The completed MCP server and client integration!

Deliverables

• A short Loom of either:
  • the MCP server you built and a demo of the client interacting with it; or
  • the notebook you created for the Advanced Build

Share 🚀

Make a social media post about your final application!

Deliverables

• Make a post on any social media platform about what you built!

Here's a template to get you started:

🚀 Exciting News! 🚀

I am thrilled to announce that I have just built and shipped an MCP server with OAuth authentication! 🎉🤖

🔍 Three Key Takeaways:
1️⃣
2️⃣
3️⃣

Let's continue pushing the boundaries of what's possible in the world of AI and tool integration. Here's to many more innovations! 🚀
Shout out to @AIMakerspace !

#MCP #ModelContextProtocol #OAuth #Innovation #AI #TechMilestone

Feel free to reach out if you're curious or would like to collaborate on similar projects! 🤝🔥

Submitting Your Homework [OPTIONAL]

Main Homework Assignment

Follow these steps to prepare and submit your homework assignment:

1. Review the MCP server code in server.py and the app/ directory
2. Run the MCP server locally using uv run server.py
3. Connect to the server using an MCP client (e.g., Claude Desktop, or a custom client)
4. Test all available tools: browsing products, adding to cart, viewing cart, removing items, and checkout
5. Record a Loom video reviewing what you have learned from this session

Questions

❓ Question #1:

Why is OAuth important for MCP servers, and what security considerations should you keep in mind when exposing tools to AI clients?

✅ Answer:

❓ Question #2:

What is the Agent-to-Agent (A2A) protocol, and how does it differ from MCP in terms of purpose and architecture? When would you choose A2A over MCP?

✅ Answer:

Activity 1: Extend the MCP Server

Add at least one new tool to the cat shop MCP server (e.g., search_products, update_cart_quantity, or get_order_history). Ensure the new tool integrates properly with the existing database and OAuth authentication. Demo the new tool through an MCP client and include it in your Loom video.

Advanced Activity: Build a Custom MCP Client

Build a custom MCP client that connects to the cat shop server over Streamable HTTP, authenticates via OAuth, and orchestrates a multi-step shopping flow (browse → add to cart → checkout). Compare the developer experience of MCP-based tool integration vs. traditional REST API calls.

Include your findings and a demo in your Loom video.