gitwtfhub

wtf is nextjs-agent-mcp-starter?

buildbase-app/nextjs-agent-mcp-starter — explained in plain English

Analysis updated 2026-05-18

0TypeScriptAudience · developerComplexity · 4/5LicenseSetup · hard

TL;DR

A Next.js starter template that lets AI agents, not humans, authenticate and call tools via a built-in MCP server, using BuildBase for agent OAuth login and access control.

Mindmap

mindmap
  root((agent mcp starter))
    What it does
      Live MCP server
      Agent only OAuth login
      48 callable tools
    Tech stack
      Next.js
      TypeScript
      BuildBase SDK
      MCP protocol
    Use cases
      Agent first apps
      Scoped tool access
      Reference implementation
    Audience
      Developers
      AI agent builders

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Build an app that AI agents like Claude Code can log into and control directly instead of a human using a UI.

REASON 2

Expose a set of safe, scoped tools (like project CRUD) for an agent to call under a specific user's permissions.

REASON 3

Use as a reference for wiring agent OAuth with dynamic client registration and PKCE in a Next.js app.

What's in the stack?

TypeScriptNext.jsMCPBuildBase SDKNode.js

How it stacks up

buildbase-app/nextjs-agent-mcp-starter0xradioac7iv/tempfs52191314/web-agent-proxy-sdk
Stars000
LanguageTypeScriptTypeScriptTypeScript
Setup difficultyhardmoderatemoderate
Complexity4/53/54/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · hard Time to first run · 1h+

Requires a BuildBase account, an OAuth2 agent client with Agent Readiness enabled, and a public tunnel like ngrok since localhost does not work for the agent auth flow.

MIT license, free to use, modify, and distribute, including commercially, with the copyright notice kept.

Wtf does this do

This is a starter template for building a Next.js application that AI agents, rather than humans, log into and use directly. It is built on the BuildBase SDK and sets up a live MCP server, the protocol AI clients like Claude Code use to discover and call tools, along with a full login system designed specifically for agents. There is no login screen for people in this app. Instead, users approve access on BuildBase's own hosted login and consent page while an AI agent is going through its authentication flow in the background. The starter requires a BuildBase account with an agent OAuth client set up and a feature called Agent Readiness turned on, without which agents cannot log in at all. Out of the box, the template exposes 48 tools an agent can call: 42 built in BuildBase tools covering things like workspaces, users, billing, and permissions, including both safe read actions and destructive ones like deleting a workspace or canceling a subscription, plus a small custom example tool and five example tools for managing projects. The project management tools use a temporary in memory store meant only as a demonstration, so it resets whenever the server restarts and would need to be replaced with a real database for actual use. The README is clear that this broad tool exposure is meant to show what is possible, and that a real deployment should narrow it down to read only access or a specific allow list before going live. It also notes some production safeguards already included, such as rate limiting per user, environment variable checks that fail loudly if something is missing, and error messages that hide internal details from agents while still logging full errors for developers. Every action an agent takes runs under the permissions of the human user who granted access, so an agent can never do more than that person is allowed to do.

Yoink these prompts

Prompt 1
Walk me through setting up a BuildBase OAuth2 agent client for this starter and connecting Claude Code to it.
Prompt 2
Show me how to narrow the exposed tools in src/lib/agent.ts to read-only before deploying this to production.
Prompt 3
Help me replace the in-memory project store in this starter with a real database.
Prompt 4
Explain how agent authentication works in this template versus normal human login.
Prompt 5
What production hardening does this starter already include, and what's still missing before I go live?

Frequently asked questions

wtf is nextjs-agent-mcp-starter?

A Next.js starter template that lets AI agents, not humans, authenticate and call tools via a built-in MCP server, using BuildBase for agent OAuth login and access control.

What language is nextjs-agent-mcp-starter written in?

Mainly TypeScript. The stack also includes TypeScript, Next.js, MCP.

What license does nextjs-agent-mcp-starter use?

MIT license, free to use, modify, and distribute, including commercially, with the copyright notice kept.

How hard is nextjs-agent-mcp-starter to set up?

Setup difficulty is rated hard, with roughly 1h+ to a first successful run.

Who is nextjs-agent-mcp-starter for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.