Skip to main content
The Headless API is designed to work with AI from the start. If you give an AI assistant the right context, you can build or customize the whole theme by chatting.

Four sources of context for the AI

1

Create the template

The template ships with AGENTS.md, CLAUDE.md and .mcp.json; no extra setup is needed.
2

Start the assistant in the project folder

or open the folder in Cursor / Windsurf. The assistant reads AGENTS.md automatically and connects the MCP server from .mcp.json (it may ask for approval the first time).
3

Run the dev server

Watch the result live with npm run dev.
4

Write your request

Use one of the sample prompts below.

Sample prompts

“Turn the whole site into a dark purple/neon gaming theme. Redesign the hero section on the home page and make product cards image-focused. Keep data and functionality the same.”
“Add a new /ranking page that shows the leaderboards. First check the site config and confirm the leaderboards module is on; if not, return 404.”
“On the store home page, move categories to a left sidebar and show the discount rate as a badge on product cards.”
“After logging in, the account page returns EMAIL_NOT_VERIFIED. Why? Add the right redirect.”

Method 2: An existing or empty project

If you do not use the template, give the assistant:
  1. Add the MCP server: claude mcp add leaderos -e LEADEROS_URL=... -e LEADEROS_PUBLIC_KEY=... -- npx -y @leaderos/headless-mcp
  2. Point it to the API reference in your first message:
“Read this reference: https://your-site.com/headless/llms-full.txt. We will build a Next.js store with this API. Use @leaderos/headless-sdk.”

Method 3: Chat tools (ChatGPT, Claude.ai, Gemini)

If you cannot use MCP, paste the content of llms-full.txt into the chat or upload the file, then describe the page you want. This is enough for small components and single pages; for managing a whole project, Method 1 is far more efficient.

What does AGENTS.md say?

The template’s AGENTS.md holds the rules the AI must follow, for example:
  • Branch on error codes (error.code), not messages.
  • Use requireAuth() on every page that needs a login.
  • Do not show a feature whose module is off (isModuleActive / useModule).
  • Never keep the token in client state or localStorage.
  • Show the *Formatted fields for money values.
  • Never remove or hide the <PoweredBy /> component.
Append your own rules (color palette, component library, code style) to the end of this file to steer the assistant.
The template tells the AI explicitly not to remove the “Powered by LeaderOS” link. It will refuse even if you ask; removal is only possible when config.branding.canRemove is true. This is a license requirement.

Tips for good results

  • Work in small, clear steps: “product card → store page → cart”.
  • Tell the assistant what not to change first (“don’t touch API calls and guards”).
  • After each step ask it to run npm run typecheck and npm run build.
  • Keep MCP on so it sees real data; this largely prevents invented field names.
  • After changing critical flows such as payments, always test by hand on a test site.

Security warnings

  • LEADEROS_ALLOW_WRITE=1 in MCP should only be used on a test site.
  • Do not give the AI your admin panel passwords or database credentials; the public key is all the Headless API needs.
  • Review generated code before going live, especially form submissions and payment flows.