Project Setup & Configuration

Create an MCP App with json-render

Chapter 1 · Project Setup & Configuration

📺 Based on the LinkedIn Learning course "Create an MCP App with json-render" by instructor Eve Porcello, published 17 April 2026. View the original course →

What Is JSON Render?

JSON Render is the core tool this course is built around — a pipeline that turns a plain-language prompt into a structured JSON spec, which is then rendered into real, live UI components. The idea splits neatly into two halves: an AI model decides what should appear on screen (expressed as JSON, not raw markup), and a separate rendering layer decides how that JSON actually becomes pixels. That separation is what makes the same spec usable in more than one place — a theme this course returns to directly in Chapter 4, once the same components get exposed to AI agents over MCP as well as to a browser.

The Project Stack

Tool	Role in this project
Next.js	The application framework — routing, API routes, and the React rendering layer
TypeScript	Typed JavaScript — catches spec/component mismatches at build time rather than runtime
Tailwind CSS	Utility-class styling for every rendered component
ESLint	Linting, keeping the generated and hand-written code consistent
Shadcn (Shad CN)	The actual component library the catalog draws from — real, pre-built UI primitives (cards, badges, stacks) rather than building each one from scratch
Vercel AI SDK	The library used to stream AI-generated output back to the client
Zod	Schema validation — used to make sure an AI-generated spec actually matches the shape the renderer expects before it's trusted

Key Packages

Alongside the standard Next.js scaffold, this project installs a small, purpose-built set of packages:

npm install @jsonrender/core @jsonrender/react-schema @jsonrender/shad-cn
npm install ai zod

@jsonrender/core — the core spec-to-render engine
@jsonrender/react-schema — the schema layer describing what a valid spec can contain
@jsonrender/shad-cn — the Shadcn-specific bindings, connecting the schema's component types to real Shadcn components
ai — the Vercel AI SDK itself, used for streaming model output
zod — schema validation, used throughout to keep AI-generated data honest

Authentication: The Vercel AI Gateway

Rather than managing a separate API key for every individual model provider, this project authenticates through the Vercel AI Gateway — a single API key, stored in .env.local, that unlocks access to multiple different LLM models through one consistent interface.

# .env.local
AI_GATEWAY_API_KEY=your_key_here

Why This Matters

A single gateway key means the model used later in Chapter 3's own API route (Claude Haiku 4.5) can be swapped for a different model without touching authentication code at all — the gateway, not the individual provider, is what the app actually talks to.

A Standard, Worth-Repeating Caution

.env.local should never be committed to version control — it's the file real API keys live in, and Next.js's own default .gitignore already excludes it for exactly this reason.

Hands-On Exercises

Exercise 1

Explain, in your own words, why JSON Render's approach — an AI model producing a JSON spec, with a separate renderer turning that spec into UI — is different from simply asking a model to generate raw HTML or JSX directly.

📄 View solution

Exercise 2

Match each of the three @jsonrender/* packages (core, react-schema, shad-cn) to the specific real job it does in the pipeline, and explain why the project needs all three rather than just one combined package.

📄 View solution

Exercise 3

A teammate suggests hardcoding the AI Gateway API key directly into route.ts instead of using .env.local, "to save a step." Explain, in your own words, why this is a bad idea.

📄 View solution

Chapter 1 Quick Reference

JSON Render: prompt → JSON spec → rendered UI, with generation and rendering deliberately kept separate
Stack: Next.js, TypeScript, Tailwind, ESLint, Shadcn, Vercel AI SDK, Zod
Core packages: @jsonrender/core, @jsonrender/react-schema, @jsonrender/shad-cn, plus ai and zod
Auth via the Vercel AI Gateway — one API key in .env.local, multiple models