The agent loop,
explained like you are five
Project #1 built a server that waits to be told what to do. This is the thing that does the telling. It reads your sentence, picks the tools, runs them, reads the results, and decides what's next — over and over, until it has an answer.
An “AI agent” sounds like a thing you buy. It's a while loop. Here it is.
Server, client, host
Three words that get used interchangeably and shouldn't be. The difference is who owns the thinking.
A server offers tools
It sits there and waits. When somebody asks, it does the thing and hands back an answer. That was project #1 — a vending machine.
A client talks to one
It knows how to speak the protocol — handshake, read the list, call a tool. Useful, but it doesn't decide anything.
A host owns the loop
It wrangles several servers, holds the conversation with the model, and keeps going until the job is done. That red box is every AI product you admire.
When you said “roll me three d20s” in Claude Desktop, your server rolled the dice — and Claude Desktop did everything else. Reading your intent, choosing the tool, inventing the arguments, reading the result, writing the sentence. This project is that everything else.
The whole loop, in four steps
There is no magic in here either. It is a while loop with an API call in it.
Ask the model
Send the whole conversation to Claude, along with a list of every tool from every connected MCP server. The API is stateless — you resend all of it, every single time.
It answers, or it asks
The reply either IS the answer, or it's a request: “please run roll_dice with sides 20 and times 3.” That difference is one field: stop_reason.
Run the tool, paste the result
Call the real MCP server, take what comes back, and paste it into the conversation as if the user had said it. Then go back to step 1.
…until it stops asking
When stop_reason is end_turn, you're done. Cap the loop at ten trips, because a loop with a bug is not a hang — it's a bill.
Step 3 is where it stops being a chatbot. Ask it to roll 3d20 and then put that many cookies in the jar. The dice total from the first tool becomes the argument to the second — and nobody wrote that wire. No code in this app knows dice have anything to do with cookies. It emerges from pasting the result back and asking again.
Try it yourself, right now
This is a real loop against two real MCP servers — project #1's cookie jar, live on the internet, and a second one running at /api/toolbox. Every tool call, argument, result and token count is shown as it happens. Nothing is hidden.
Pick one, or ask your own.
Start with the first one — it's the whole lesson in a sentence.
What turns a loop into a host
The loop is the interesting part. These three are what you need around it before anyone else can use the thing.
Many servers, one shelf
A client talks to one server. A host connects to several and hands the model one combined toolbox. If a server is down, the others still work — the loop degrades instead of dying.
Namespaced tools
Both servers here offer a secret_code tool, on purpose. Without namespacing one silently shadows the other. The host rewrites them to cookiejar__secret_code and toolbox__secret_code.
Seatbelts
A hard cap of ten iterations, explicit stop_reason handling, and a live token meter. Prompt caching cuts the repeated prefix by about half — you can watch it work in the trace.
This project ships a server too
The host needed a second server to prove it could juggle more than one, so there's a small MCP server in this repo. You can plug it into Claude Code like any other.
claude mcp add --transport http agent-lab-toolbox https://learn-mcp-agent-loop.vercel.app/api/toolbox
It offers current_time, calculate, word_count and secret_code — four things a language model genuinely cannot do reliably in its head.