🔨Build it

The full walkthrough is BUILD_FROM_SCRATCH.md. This is the shape, and the seven things that broke.

1. 0–1

   Prerequisites, scaffold and install

   An ANTHROPIC_API_KEY this time — project #2 is the first one that costs money to run.

   Same scaffolding gotcha as project #1: create-next-app refuses a non-empty folder. Temp dir, then copy in.

2. 2

   Read the types before you write any code

   The habit that changed the design in all five projects.

   ✅ Checkpoint

   You can state, from memory, the exact signature of registerTool and whether your model accepts temperature.

3. 3

   The MCP client

   About two hundred lines of fetch — see Writing the client by hand.

   ✅ Checkpoint

   Run it against the live project #1 server, not a local one:

   bashcopy

   npm run mcp:list

4. 4

   Schema translation

   inputSchema → input_schema, strip $schema, substitute an empty object for a missing one.

   ✅ Checkpoint

   bashcopy

   npm run mcp:translate

5. 5

   The agent loop (non-streaming)

   Get it right before making it pretty.

   ✅ Checkpoint

   The demo, in a terminal, before any React exists:

   bashcopy

   npm run agent

   Two tool calls across two iterations, with the second one's count matching the first one's total.

6. 6–7

   The route handler and the chat UI

   The key is read in exactly one place. The browser sends plain text and receives an NDJSON stream of loop events.

   ✅ Checkpoint

   bashcopy

   curl -N -X POST http://localhost:3000/api/chat \
     -H "Content-Type: application/json" \
     -d '{"messages":[{"role":"user","content":"roll one d6"}]}'

7. 8

   The second MCP server

   In this repo, at /api/toolbox — and with a deliberate secret_code collision, so namespacing has something to prove itself against.

8. 9

   Auth on your own server

   withMcpAuth and a shared token.

   ✅ Checkpoint

   With MCP_SHARED_TOKEN set and the dev server restarted: no token gives 401, the right token gives 200.

9. 10–12

   Typecheck, build, GitHub, deploy

   bashcopy

   npx tsc --noEmit && npx eslint . && npm run build

   ✅ Checkpoint

   Verify against production, not localhost.

The gotcha worth the whole page

The reason this one is nasty: it works perfectly in development, works perfectly in preview if protection happens to be off, and fails only in the configuration you ship. And the symptom — "my MCP server is down" — points at the server, which is fine.

The other six

.env* swallows .env.example. The Next.js .gitignore ships with .env*, which also matches the example file you actually want committed. Add !.env.example and keep that block last, because a later pattern wins.

The dev server that would not die. Killing the shell that started it does not kill it. Check the port, not the shell:

Get-NetTCPConnection -LocalPort 3000 -State Listen

This one bit project #3 and project #4 as well. Three projects, same surprise — which is a good sign the mental model is wrong rather than the command.

.env.local is read at startup, not per request. Add a variable, and the running dev server does not know about it. Restart, then re-test — otherwise you will "fix" a working config three times.