AI App Boilerplate
A Next.js + Claude chat app with streaming, a tool trace, MCP and approval before writes.
Who it's for
- You are building an assistant on top of your own system (a CRM, a database, an internal API) and need it to read freely but change nothing without a person approving it.
- You want to see every tool call the model makes, and an audit that checks what ran against what was approved.
- You want sign-in with your company's identity provider when you deploy, and a local mode that needs only an API key.
Not for you if you need chat history stored in a database, teams and billing, file uploads and retrieval pipelines, or providers other than Anthropic: those are not included.
What's inside
One Next.js 16 project folder. Claude reads through tools you can watch in a trace panel, proposes every change as an approval card, and runs it only after you approve that exact call.
- Routes: the chat, report and notes pages and the API handlers for the chat stream, the report, health and OpenID Connect sign-in.
- Modules: validated configuration, the Claude request builder, the chat turn and approval logic, the local tool registry, the write audit, MCP server settings, sealed cookie sessions, OIDC sign-in with PKCE, rate limiting and the stream and trace helpers.
- Components: the chat, the tool trace panel, the approval card, the report and a safe Markdown renderer.
- 4 example tools over a demo notes store: search and read notes, and create and delete notes (both writes).
- Tests: Vitest files in which every call to Anthropic, the identity provider and MCP is mocked.
- Guides: getting started, architecture, tools, MCP servers, sign-in, security, deployment and testing.
- App routes (pages and API)
- 9
- app/api/auth/callback/route.ts
- app/api/auth/login/route.ts
- app/api/auth/logout/route.ts
- app/api/chat/route.ts
- app/api/health/route.ts
- app/api/report/route.ts
- app/notes/page.tsx
- app/page.tsx
- app/report/page.tsx
- Library modules
- 17
- lib/anthropic.ts
- lib/audit.ts
- lib/auth/dev.ts
- lib/auth/oidc.ts
- lib/auth/pkce.ts
- lib/chat.ts
- lib/config.ts
- lib/http.ts
- lib/local-tools.ts
- lib/mcp-servers.ts
- lib/ndjson.ts
- lib/rate-limit.ts
- lib/report.ts
- lib/route-guard.ts
- lib/session.ts
- lib/trace.ts
- lib/types.ts
- UI components
- 6
- components/Chat.tsx
- components/Markdown.tsx
- components/ProposalCard.tsx
- components/Report.tsx
- components/Topbar.tsx
- components/TracePanel.tsx
- Example tools
- 4
- tools/create-note.ts
- tools/delete-note.ts
- tools/get-note.ts
- tools/search-notes.ts
- Tests (mocked APIs, no network)
- 14
- tests/anthropic.test.ts
- tests/chat-route.test.ts
- tests/client-bundle.test.ts
- tests/config.test.ts
- tests/local-tools.test.ts
- tests/markdown.test.ts
- tests/mcp-servers.test.ts
- tests/oidc.test.ts
- tests/pkce.test.ts
- tests/rate-limit.test.ts
- tests/report.test.ts
- tests/route-guard.test.ts
- tests/session.test.ts
- tests/stream-and-trace.test.ts
- Guides
- 8
- docs/architecture.md
- docs/auth.md
- docs/deployment.md
- docs/getting-started.md
- docs/mcp.md
- docs/security.md
- docs/testing.md
- docs/tools.md
Files
Files
Files
Files
Files
Files
In the zip · 79 files · 188 KB
- .env.example
- .github/1 files
- .gitignore
- CHANGELOG.md
- LICENSE.md
- README.md
- app/11 files
- components/6 files
- docs/8 files
- eslint.config.mjs
- instrumentation.ts
- lib/17 files
- next.config.ts
- package-lock.json
- package.json
- scripts/1 files
- tests/17 files
- tools/6 files
- tsconfig.json
- vitest.config.mts
Setup
Requirements
- Node.js 22.12 or newer and npm
- An Anthropic API key (billed by Anthropic); the tests and the build run without one
- Optional: an OpenID Connect provider (Microsoft Entra ID, Google, Okta, Auth0, Keycloak...) for multi-user sign-in
- Optional: remote MCP servers reachable from the internet over https (Anthropic's MCP connector calls them)
- Unzip and install:
cd ai-app-boilerplate && npm ci && cp .env.example .env.local. - Set
ANTHROPIC_API_KEYin.env.localand leave the rest as it is. npm run dev, open http://localhost:3000 and choose Continue as local developer.- Ask "What do my notes say about the 1.4 release?" and watch the trace.
- Ask it to create a note, read the approval card and click Approve.
Time to first result: about 3 minutes.
Tested with
Clean-install test passed on 2026-10-01 (darwin-arm64, node 22.23.2, npm 10.9.8): extract, base, node, yaml, docs, acceptance.
Licence
You may use this product in unlimited personal and commercial projects, including client work. You may not resell, redistribute, sublicense or share the product itself, in whole or in part, including as a template, starter kit or course material. One purchase covers one person.
The full licence is in LICENSE.md inside the zip. Site terms: /terms.
Questions
When can I buy it?
When it has run against the live Anthropic API, a real identity provider and a real MCP server, with live screenshots. The offline tests, lint, type checks and the production build already pass on a clean install. I haven't set a date; leave your email above and I'll tell you when it's on sale.
Do I need an API key?
Yes, an Anthropic API key to chat (usage is billed by Anthropic). The tests and the build run without one.
How do MCP servers connect?
Through Anthropic's MCP connector: the servers must be reachable over https from the internet. Local tools are plain server-side functions you register in the tool list.
How do updates work?
New versions go to your Gumroad library; download them from there. Changes are listed in the CHANGELOG inside the zip.
Can I use it for client work?
Yes. Apps you build from it, for yourself or for clients, are yours. You can't resell or share the boilerplate itself.