For AI Agents
This page is the canonical entry point for AI assistants (Claude Code, Cursor, Copilot, custom agents) that need to write code against @ngrok/mantle.
TL;DR for the agent
Connect over MCP
mantle runs a hosted MCP server at https://mantle.ngrok.com/mcp. Connect your agent to it, and the agent reads the API of the mantle version you installed instead of guessing from its training data. The server has no sign-in, and it never stores your code.
Add it to Claude Code:
To give everyone on a repo the server, commit it to the project config. Claude Code reads .mcp.json at the repo root:
Cursor reads the same mcpServers shape from .cursor/mcp.json. VS Code reads .vscode/mcp.json, with servers in place of mcpServers. Codex reads ~/.codex/config.toml:
The server tells the agent when to call each tool, so you don't have to:
Pass the exact installed version (from node_modules/@ngrok/mantle/package.json or the lockfile), not the range in package.json. The server supports 0.90.0 and later.
Each tool takes an optional intent: the goal of the call in generic words, such as "endpoints list page, add bulk delete, need a confirm step for a destructive action". Each tool also takes an optional workspace: the app or package that the agent changes, such as "dashboard", and an optional ticket: the Linear issue key of the work, such as "FEP-1867" or "MNTL-59". The agent sends the ticket when it knows the issue, for example when the user names it. report_gap requires a ticket: the key, or "none". The mantle team reads them to learn what agents build, where, and where mantle falls short. For each call, the server logs these values:
- the tool name, the outcome, and the error kind
- the client name from the
User-Agentheader - the
sourcequery parameter of the MCP URL, when it names an ngrok repo - the names of the parts that the tool returned
- the intent, with each word that holds a URL, an email, a path, or a number removed. Words in quotes stay. The server drops an intent that holds a code span, a tag, a call, or an assignment.
- the workspace, when it is a slug of up to 32 lowercase letters, digits, and hyphens and the MCP URL has a
source - the ticket, when it is an issue key and the MCP URL has a
source
The server never logs the code that you send to check or preview.
In chat apps that support MCP Apps, such as Claude, ChatGPT, and VS Code, preview shows the prototype in the conversation. The prototype runs in the same sandboxed frame as the preview link. If the chat app cannot show the frame, the view shows an Open in browser button. Other clients get the link.
Install the agent skill
mantle publishes an Agent Skills skill that teaches your agent the mantle workflow: find a part, read its contract for your installed version, import it from its own subpath, and check the file. Install it with:
The skill uses the MCP server when your client has it connected, and the files in node_modules/@ngrok/mantle/dist/ when it does not.
Machine-readable entry points
Design tokens
mantle ships its design tokens as @ngrok/mantle/tokens.json, in the Design Tokens Community Group (DTCG) format, version 2025.10. The file holds every color, font, size, radius, shadow, and breakpoint token with its light theme value. @ngrok/mantle/tokens.dark.json holds the tokens that change in the dark theme, and @ngrok/mantle/tokens.resolver.json is a DTCG resolver document that applies the dark file for the dark context. A token path joined with - names its Tailwind theme variable: color.sky.500 is --color-sky-500.
Suggested system-prompt snippet
Drop this near the top of an agent's system prompt when working in a mantle codebase:
Conventions agents should know
- Polymorphism via
asChild. Most components acceptasChild(powered bySlot). Use it to render the component as a different element (for example, render aButtonas areact-routerLink) without losing the component's styling or behavior. - Flat import paths, categorized docs URLs. Components import from
@ngrok/mantle/<name>(e.g.@ngrok/mantle/button). The docs URL's category segment (/components/actions/button) never appears in import paths. Hooks live at@ngrok/mantle/hooks(e.g.import { useBreakpoint } from "@ngrok/mantle/hooks"). Utilities live at their own subpaths:@ngrok/mantle/cx,@ngrok/mantle/color, etc. - Docs slug ≠ import subpath (sometimes). Most components import from a subpath that matches their docs slug (e.g.,
Buttonfrom@ngrok/mantle/button). A few are exported from a parent's subpath:IconButtonfrom@ngrok/mantle/button,PasswordInputfrom@ngrok/mantle/input,ProgressBarandProgressDonutfrom@ngrok/mantle/progress. The structured manifest at/api/components.jsonis the source of truth; itsimportPathfield is always correct. cxover string interpolation. Compose class names withcx. It merges Tailwind classes and de-duplicates conflicts.- Theme + provider setup. Apps must mount
ThemeProviderandToasterat the root. AddTooltipProvideronce when using shared tooltip delay or hover settings. WithoutThemeProvider, theme tokens are unstyled and there's a flash of unstyled content. - Stylesheet setup. The app's CSS entry imports
@ngrok/mantle/mantle.cssand then@ngrok/mantle/source-all.css(see Stylesheet).mantle.cssdeclares no@source, and Tailwind 4 skipsnode_moduleswhen it scans for class names, so withoutsource-all.cssTailwind generates none of the classes mantle's components use. The components render without their styles. An openDialogshows its content in the page flow with no backdrop. Import both from the same CSS file: Tailwind compiles each CSS entry on its own, so an@sourcein a separate file adds nothing. To trim the production stylesheet, addmantleSourcesPlugin()from@ngrok/mantle-vite-pluginsnext totailwindcss()invite.config.ts. The CSS file does not change. - Phosphor icons by default. Import icons from
@phosphor-icons/react/<IconName>(e.g.@phosphor-icons/react/Fire). Custom ngrok icons live at@ngrok/mantle/icons. - Translation-safe markup. Google Translate reparents every text node, so React throws
NotFoundErrorand the page goes blank when it inserts an element before one. Never render a conditional element immediately before bare text children: wrap the text in a<span>, move the element after it, or mount it unconditionally. Pass aButtonorBadgeicon through theiconprop, never as a child. Mark code, keys, filenames, IDs, and passcodestranslate="no";Code,Kbd,CodeBlock.Code, andOtpInput.Slotalready do. The attribute classifies content and is never the fix for a crash: when a shape throws, fix the structure, and keep prose translatable. - 320px minimum width. Design for a viewport 320px wide and wider (see Breakpoints). At 320px, the page doesn't scroll sideways and no content is cut off. A table, a code block, or a tab list can scroll inside its own box. Below 320px, a layout problem isn't a bug.
- Tailwind 4. Custom classes use the design tokens defined in
mantle.css. Prefer semantic tokens (text-strong,bg-form,border-accent-600) over raw color names where they exist. Color scales use Tailwind's50–950steps (text-accent-600,bg-neutral-100); there is no1–12scale, sotext-accent-11matches nothing. The text color tokens are on Typography and the palettes on Colors.
Composition patterns
A few high-leverage compositions agents commonly need:
Accessibility-first defaults
Every mantle component is built on semantic HTML and tested ARIA patterns. Agents should:
- Render real form controls (
Input,Checkbox,RadioGroup); never style a<div>with click handlers as a button. - Pair every form control with a
Label. - Use
SkipToMainLink+Mainat the top of the document tree. - Set accessible names for icon-only buttons via the required
labelprop onIconButton. - See the Accessibility page for a full keyboard / ARIA reference per component.
When to ask vs. when to act
- If the user asks for "a primary button," generate a
Buttonwithappearance="filled" intent="neutral", the system's default primary action.ButtonandIconButtonrequire explicitappearanceandintent; there are no defaults. The two take different tone unions:Buttontakes"accent","danger", or"neutral". Useintent="neutral"when no tone is implied. Reserveintent="accent"for deliberate brand emphasis: an action that should carry the accent color.IconButtontakes"neutral"alone. Reach forButtonwhere the tone carries meaning.
- If choosing between
Tooltip,Popover, andHoverCard, follow the JSDoc guidance:Tooltipfor short label hints,Popoverfor interactive content,HoverCardfor non-essential preview cards. - If choosing between
DataTableandTable:DataTablefor dynamic, sortable, filterable, paginated tabular data;Tablefor static layout. - When uncertain, prefer to fetch the relevant
/<page>.mdand read the full doc rather than guessing.
Versioning
@ngrok/mantle is 0.x, so stock semver does not apply. There is no major: a breaking change ships as a minor, and an additive or internal change ships as a patch. Read the Changelog before a minor bump, and run the matching migration guide when one exists. When working in a project, check package.json for the pinned version and prefer the docs at the matching tag on GitHub if you need to pin behavior to that version.