BuildBase Agent MCP Starter (nextjs-agent-mcp-starter)

Next.js 16 (App Router) + @buildbase/sdk ≥ 0.0.54 starter for an agent-first app: a live MCP server with BuildBase-powered agent OAuth and the full agent-discovery surface, all from one createAgentStack() config.

Important: This starter requires a BuildBase account with an OAuth2 agent client and Agent Readiness enabled. Without it, agents cannot authenticate.

Agent auth only. There is no app-side login UI — users authenticate on BuildBase's hosted login + consent screen during the agent's OAuth flow. (For human sign-in wiring, see the nextjs-starter reference app.)

Verified end-to-end with Claude Code as the MCP client: discovery → dynamic client registration → consent → token mint → 31 tools, including writes.

Setup

1. Copy .env.example → .env.local and fill it in (see Environment).

2. In console.buildbase.app:

   • Create an OAuth2 agent client (Type oauth2, Client kind Agent (third-party), PKCE on) with:

     • Application Token URL → https://<your-public-origin>/api/agent/token

     • Application Revoke URL → https://<your-public-origin>/api/agent/token/revoke

     • Application Profile URL → https://<your-public-origin>/api/profile

     • Redirect URLs: leave empty — agents register their own via DCR.

   • Admin → Auth → Agent access: enable Agent readiness and Let agents register themselves, picking the client above as the base client.

3. npm install && npm run build && npm start, then connect an agent:

   claude mcp add --transport http my-app https://<your-public-origin>/mcp

localhost will not work for the agent flow — the BuildBase platform calls your token endpoints server-to-server and blocks loopback addresses. For local dev, tunnel (ngrok http 3000) and use the tunnel origin in the console URLs and NEXT_PUBLIC_SITE_URL.

Related MCP server: agentforge

Environment

NEXT_PUBLIC_* values are inlined at build time — rebuild after changing them.

What's wired

Tools exposed (48)

• 42 BuildBase built-in tools — the complete catalog, listed explicitly in builtinTools.include (grouped by category in src/lib/agent.ts): every read (workspaces, users, subscription, plans, invoices, quota, usage logs, credits, feature flags, permissions, settings) and every write, including destructive operations (delete_workspace, cancel_subscription, remove_workspace_user, …). Narrowing the surface is just deleting lines.

• app_health — minimal custom-tool example.

• 5 project CRUD tools (create/list/get/update/delete_project) — a complete custom-tool example with zod schemas, annotations, and per-user ownership scoping via ctx.auth.userId.

This starter deliberately exposes the full surface to demonstrate capability. For production, narrow it: builtinTools: 'readonly' (least privilege) or { include: [...] } / { exclude: [...] } with exactly the operations you want agents to perform. Whatever you expose, every call runs under the granting user's session — an agent can never exceed its user's permissions.

⚠️ The project tools use an in-memory demo store: it resets on every server restart and is not shared across serverless instances. Swap projectStore in src/lib/agent.ts for your real database; the tool logic stays the same.

Every tool runs under the granting user's BuildBase session — an agent can never exceed its user's permissions.

After adding/changing tools: rebuild + restart, then reconnect in the client (/mcp → Reconnect in Claude Code) — MCP clients cache tools/list per connection.

Production hardening (already wired)

• Env fail-fast — missing required env fails the build with a clear message instead of a silently broken discovery surface.

• Rate limiting — 120 req/min per user (sliding window, in-memory; back with Redis/KV or an edge limiter when scaling out).

• Error redaction — tools throw ToolError for agent-facing messages; anything else returns a generic message in production while the full error goes to onError logging.

• Request-size cap — SDK default 1 MiB (413 above it).

• CI — lint + build + typecheck on every push/PR (.github/workflows/ci.yml).

Before going live

• Deploy behind a real domain; update NEXT_PUBLIC_SITE_URL + the console client URLs (Token/Revoke/Profile).

• Replace the demo project store with a database.

• Prune the builtinTools.include list — start by removing the "Destructive" group.

• If browser-based MCP clients must be restricted, set allowedOrigins in mcp.handler.

• Point onError at your real telemetry instead of console.error.