agentbuilder-assignment4

# Assignment 4: Build an MCP Agent **Given:** July 5, 2026 **Due:** July 12, 2026 (one week) **Marks:** 100 ## What you will build You will build **your own MCP server** and a **LangGraph agent** that uses it. The agent will connect to **three MCP servers at the same time**: the one you build, plus two public ones that other people already made. The agent picks the right tool from the right server to answer a question. That is the whole task. You are not building a big app. You are learning how to make an MCP server, run it over HTTP, and plug it into an agent next to other servers. ## How it fits together  Read the picture like this: - The **user** asks a question. - The **LangGraph agent** thinks. If it needs a tool, it calls one, gets the result, and thinks again. When it is done, it answers. - `MultiServerMCPClient` connects to all three servers when the program starts and gives every tool to the agent. - The **blue server is the one you build.** The **green servers are public** ones you take from a directory. ## What to build ### Part 1: Your MCP server Build one MCP server in Python with **FastMCP**. It must run over **Streamable HTTP** (not stdio). It must have: - **At least 4 tools** that together do full **CRUD**: **C**reate, **R**ead, **U**pdate, **D**elete on a small data store (SQLite is fine). - **At least 1 resource** (read only, has a URI). - **At least 1 prompt** (a reusable template). Run it with `mcp.run(transport="http", port=8000)`. It will be live at `http://127.0.0.1:8000/mcp`. ### Part 2: Test it in the Inspector Before you write the agent, open the **MCP Inspector** and call your tools by hand: ```bash npx @modelcontextprotocol/inspector ``` Choose "Streamable HTTP" and enter `http://127.0.0.1:8000/mcp`. Call one tool that writes data, then read it back. **Take a screenshot.** ### Part 3: Your LangGraph agent Build a LangGraph agent with `MultiServerMCPClient`. It must connect to **three servers**: your server plus **two public servers** from a directory. Good, safe public servers (no API key needed): - `fetch` (get a web page as text): `uvx mcp-server-fetch` - `time` (current time, time zones): `uvx mcp-server-time` More options and exact config are in **[public-servers.md](public-servers.md)**. Where to find servers: `github.com/punkpeye/awesome-mcp-servers`, `registry.modelcontextprotocol.io`, `glama.ai/mcp/servers`, `smithery.ai`. ### Part 4: Show it working, and record a video Run **three example questions**. Each one is an "output" of your project. At least one question must **write** to your server, and at least one must use a **public** server. Save the answers (a screenshot or a text file). Then record a short **video** (2 to 5 minutes) where you explain the demo, the architecture, how MCP is connected, and show the tool calls happening. Details are in "What to submit" below. ## Pick a topic You may build any topic you like. It must **not** be natural-language-to-SQL (we did that in class). The agent should **change and add data**, not run free SQL queries. If you want a ready idea, build a **Trip Planner** (recommended): - **Store:** trips, then destinations in a trip, then activities in a destination. - **Your 6 tools:** `create_trip`, `add_destination`, `list_destinations`, `add_activity`, `toggle_activity_booked`, `delete_destination`. - **Public servers:** `time` (local time at a city) and `fetch` (facts about a place). - **Example question:** "Add a 3 night stop in Kyoto to trip 1, and tell me the local time in Kyoto right now." The agent writes to your server and reads the public time server in one step. Other good topics: Reading List, Recipe and Pantry, Expense Tracker, Habit Tracker. Short descriptions of each are at the end of this file. There is a ready starter in **[starter/](starter/)**. It is a Trip Planner server with 3 tools done and 3 left for you. You can use it or start fresh. ## What to submit You submit **two things**: your **code** and a **video**. **1. Your code** (a GitHub repo or a zip): ``` your-project/ server.py your MCP server agent.py your LangGraph agent requirements.txt .env.example list the keys needed, do NOT commit real keys README.md see below screenshots/ inspector.png the Inspector calling one of your tools demo.png (or demo.txt) your 3 example questions and answers ``` Your `README.md` must say: 1. Which topic you built. 2. Your tables, your tools, your resource, and your prompt. 3. Which 2 public servers you used, and why. 4. How to run it (start the server, then the agent). 5. Your 3 example questions and the answers. 6. **One short paragraph:** why is it better to put tools in an MCP server than to write them as normal Python functions inside the agent? Use your own words. This shows you understood MCP. **2. A video** (2 to 5 minutes). This is not just a demo. We want to see that you understand how it works. Your video must show and explain: - **The demo:** ask your agent a question and show the answer. - **The architecture:** use your diagram (or ours) to explain how the pieces fit: the user, the LangGraph agent, the client, and the three servers. - **How MCP is connected:** show your `MultiServerMCPClient` config and point out the three servers and their transports (your HTTP server, and the two public ones). - **The tool calls happening:** show the agent picking a tool and getting a result back. Point to the printed tool calls (or the MCP Inspector) and explain what is going over the wire. Show at least one call to **your** server and one call to a **public** server. Record with any screen recorder. Upload to YouTube (unlisted is fine), Google Drive, or Loom, and put the link in your `README.md`. ## How you are scored (100 marks) | Part | Marks | What we check | | --- | --- | --- | | Your MCP server | 20 | 4+ CRUD tools, 1+ resource, 1 prompt, runs over HTTP | | LangGraph agent | 20 | Connects your server + 2 public servers, all three work | | 3 example questions | 10 | They run. One writes to your server. One uses a public server. | | **Video walkthrough** | **35** | Demo (5), architecture explained (10), how MCP is connected (10), tool calls shown live and explained (10). Technical, not just a demo. | | README and the "why MCP" paragraph | 15 | Clear steps, and the paragraph makes sense | **Bonus (up to +10):** - Call a free public API from inside one of your tools, for example Open-Meteo weather or Open Library books. (+4) - Serve REST and MCP from one FastAPI app. (+3) - Add a `ctx.info(...)` log line to a tool and show it in the Inspector. (+3) ## Steps to follow 1. Pick your topic and design 2 or 3 small tables. 2. Write `server.py` with FastMCP. Start with one tool, run it, add the rest. Look at `servers/analytics_server.py` in the workshop repo as a model. 3. Run the server over HTTP and test it in the Inspector. Take the screenshot. 4. Write `agent.py`. Connect your server plus `time` and `fetch`. 5. Run your 3 example questions. Save the output. 6. **Record your video** (2 to 5 minutes). Explain the demo, the architecture, how MCP is connected, and show the tool calls happening. 7. Write your `README.md` (with the video link) and push to GitHub before July 12. ## Rules to remember - **Never use `print()` in a stdio server.** It breaks the protocol. Use `ctx.info(...)`. - **HTTP URLs must end in `/mcp`.** The plain URL will not work. - You need **both `uv` and Node** installed. Some public servers use `uvx` (Python) and some use `npx` (Node). See `public-servers.md`. - Do **not** commit your API keys. Use `.env`, and commit only `.env.example`. ## Where to look in the workshop - Build a server: `notebooks/03_build_your_own_server.ipynb`, `servers/analytics_server.py` - HTTP and FastAPI: `servers/fastapi_integration.py` - The agent: `notebooks/04_connect_langgraph_agent.ipynb`, `clients/03_langgraph_agent.py` ## Other topic ideas (short) - **Reading List:** books you want to read, are reading, or finished. Tools to add a book, change its status, rate it, add a note, list, delete. Public servers: `fetch` + `wikipedia`. Easiest topic. - **Recipe and Pantry:** what food you have and what you want to cook. Tools to add or use a pantry item, save or delete a recipe, list them. Public servers: `fetch` + `time`. - **Expense Tracker:** your spending. Tools to add an expense, set a budget, show this month's total, list, delete. (Totals only, not free SQL.) Public servers: `time` + `fetch`. - **Habit Tracker:** habits and daily check-ins. Tools to add a habit, check in, show a streak, list, delete. Public servers: `time` + `fetch`.