Agents

MCP tools

Every tool the Archetype MCP server publishes, with its arguments, the domains get_brand reads, and an example call for each.

A connected agent gets six tools: three that read the brand, two that make something new (images and video, or a whole campaign), and one that changes the brand. This page lists every argument exactly as the server declares it. The same reference, generated from the same source, is served to agents at /llms-full.txt.

Tool	What it's for	Marked as
`get_brand`	Read the brand, one domain at a time: an index, then one item's detail.	Read-only
`search_brand`	Find anything in the brand by keyword.	Read-only
`check_against_brand`	Grade code, copy or a live page against the brand.	Read-only
`generate_media`	Make a new photo or video clip and keep it in the brand's library.	Write (creates)
`create_campaign`	Plan a whole campaign from one brief, then make its designs, images and videos.	Write (creates)
`update_brand`	Change one item in the brand, or apply, discard or undo a change.	Write (destructive)

The server works index first, then detail. Call a domain bare to see what it holds, then call it again with the handle the index gave you. Fetch only the item you need, because every response lands in the agent's context.

get_brand

Reads the brand. With no arguments it returns the brief, which is where an agent should start: BRAND.md, then every token and the logo rules inline, then an inventory of everything else with the handle that fetches each item.

Argument	Type	Required	What it does
`domain`	string, one of the domains below	No	Which part of the brand to read. Defaults to `brief`.
`handle`	string	No	The item within the domain, as its index gave it. Leave it out for the index. Ignored by `brief` and `info`.
`task`	string	No	One sentence on what you are about to make. Returns a brief of just what that work needs: the template to start from, files to read, photos by tag, parts and gaps. Leave `domain` unset.
`example`	string	No	`components` only. An example's name or id, to narrow a component to one example.
`mode`	string	No	`tokens`, or `components` and `templates` with a handle. The mode to resolve colors in, such as `dark`.
`include_tokens`	boolean	No	`components` with a handle only. `false` leaves out the `:root` block of tokens, which is the same for every component.
`variant`	string	No	Deprecated alias for `example`.
`intent`	string	No	`icons` only. What the icon needs to mean, to pick one from a custom set, such as `download`.
`include_code`	boolean	No	`artifacts` only, with no handle. Includes the full source of every artifact. Large.
`type`	string: `social`, `web`, `app` or `files`	No	`templates` only, with no handle. Only templates of this kind.
`frame`	string, number, or an array of either	No	`templates` with a handle only. Only these frames, by name or by number from 1.
`tag`	string or array of strings	No	`files` only. Assets carrying this tag. Several tags narrow further: an asset must carry all of them.
`search`	string	No	`files` only. Substring match over name, description, usage and tags.
`pages`	string	No	`files` with a handle only. Which pages of a PDF to read, such as `3` or `5-12`.

Domains

Domain	What `handle` selects	What it returns
`brief`	(none)	BRAND.md, all tokens and logo rules inline, and an index of components, templates, artifacts, icons, library tags and knowledge files. The default.
`info`	(none)	The brand's name and slug, and a count of everything served. The cheapest way to see what exists.
`tokens`	token category: `color`, `typography`, `spacing`, `radius` or `shadow`	Design tokens as W3C Design Tokens (DTCG) JSON. Where the brand has modes, each semantic color carries its other values.
`assets`	asset name, such as `Logo Dark`	Logos, favicons and other identity assets: inline SVG or a stable file URL, plus usage rules (when-to-use tags, guidance, clearspace, minimum size, misuse).
`components`	component key, such as `button`	Bare: every component's key, name and example names. With a key: each example's real HTML and CSS, with values as `var(--token)`.
`icons`	icon set slug, such as `lucide`	Bare: the icon sets the brand uses. With a slug: import syntax and license for a referenced set, or every icon as inline SVG for a custom set, plus the set's when-to-use tags and guidance.
`artifacts`	artifact handle	Bare: an index of the brand's bespoke code (backgrounds, patterns, generative graphics, motion), with when-to-use tags and guidance. With a handle: its full source, usage snippet and brand defaults.
`templates`	template key	Bare: every template with its type and frames. With a key: the finished markup with the brand's real logo, images and colors bound in, plus a `slots` list of what may change.
`files`	file name or id	The asset library: photos, illustrations and PDFs, with tags, descriptions and a stable `embedUrl`. A PDF returns its text, page by page.
`voice`	document slug, or `all`	The brand's voice and messaging documents. Bare: an index with each document's slug, status and word count.
`schema`	(none)	How to write with `update_brand`: every domain's value shape, the component model and every limit. Read it before the first write.

Read one component

{ "domain": "components", "handle": "button", "example": "Primary" }

Brief for one piece of work

{ "task": "Instagram story announcing our spring sale" }

search_brand

Keyword search across token names and roles, logo usage, component and example names, artifacts and their code, library files (including the text inside PDFs), templates and voice documents. Every hit carries the exact get_brand call that fetches it.

Argument	Type	Required	What it does
`query`	string	Yes	A case-insensitive keyword or phrase. A phrase that matches nothing is retried term by term.
`domains`	array of `tokens`, `assets`, `components`, `icons`, `artifacts`, `templates`, `files`, `voice`	No	Limit the search to these domains. Leave it out for all.

Example

{ "query": "pricing table", "domains": ["components", "templates"] }

check_against_brand

Grades work against the brand and returns a worst-first list of fixes. A finding is either a lookup (a color or typeface the brand never defined, with the token to use instead) or a judgment with a confidence (a control rebuilt from raw elements when the brand already has it). Each finding is marked as drift, a hardcoded value, or a gap the brand has no answer for.

Argument	Type	Required	What it does
`subject`	string	One of `subject` or `url`	The code, CSS, markup or copy to grade. One file at a time, up to 80,000 characters. A longer subject is refused, not cut.
`kind`	string: `code` or `copy`	No	Defaults to `code`. Pass `copy` for prose people will read, and each sentence is also checked against the brand's voice documents.
`url`	string	One of `subject` or `url`	A live page to check as a visitor sees it. It is drawn in a browser, takes up to a minute, spends the brand's AI credits and returns a `reportUrl` for a person.
`gaps`	array of strings	No	What you had to invent because the brand didn't define it, one short sentence each. They reach the brand's team.

Example

{ "subject": ".cta { background: #0a84ff; border-radius: 10px; }", "gaps": ["No focus ring color for dark surfaces"] }

Nothing about the brand is changed by a check. A url check keeps its report on the brand's Check page. See Check.

generate_media

Makes a new photograph or video clip and keeps it in the brand's library. It costs credits, so an agent should look in the library first. The brand's imagery rules are added to the prompt for it. It needs a role that can add files to the library; it does not need edits allowed on the connection.

Argument	Type	Required	What it does
`kind`	string: `image` or `video`	No	Defaults to `image`.
`prompt`	string	Yes, unless `check`	A photographer's brief: subject, setting, light, framing, mood. Describe a scene, never a logo or lettering.
`aspect`	string	No	Images: `1:1`, `4:5`, `3:2`, `2:3`, `16:9`, `9:16`. Videos: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`.
`quality`	string: `high` or `medium`	No	Images only. Defaults to `high`.
`size`	string: `1k`, `2k` or `4k`	No	Images only. Defaults to `1k` (about 1 megapixel). `2k` is about 4 and `4k` about 8, at 8 times the credits of `1k`.
`seconds`	number: 5, 10 or 15	No	Videos only. Defaults to 5.
`audio`	boolean	No	Videos only. Defaults to `true`.
`from`	array of strings	No	Library files to start from, by name or id: up to 4 for an image, 1 for a video.
`check`	string	No	The `id` an earlier video call returned, to see whether it is ready. Pass it on its own.

An image comes back when it's made, in about a minute. A video takes minutes: the call returns an id, and the agent calls again with check until the status is ready. Either way the result names the library file it became, with an embedUrl.

Example

{ "kind": "image", "prompt": "Morning light over a rooftop garden, wide shot, calm", "aspect": "16:9", "size": "2k" }

create_campaign

Has Archetype make a whole campaign from one brief: it plans the idea, the line and the look the pieces share, then makes every piece side by side. Pieces are designs from the brand's templates, components, photos and voice, and generated images and videos in the same look. It spends the brand's credits: about one Create design per design or image, and many times that per video.

It needs a role with the Designs and checks permission; images and videos also need permission to edit the Library. Like generate_media, it does not need edits allowed on the connection.

Argument	Type	Required	What it does
`brief`	string	Yes, unless `make`, `discard` or `check`	What the campaign is for, who it speaks to, where it runs, and any facts (dates, prices, offers) it must carry, in the person's words. Up to 3 full `https://` links in it are read for their words, logo and pictures, which the pieces use as that party's own.
`attach`	array of objects	No	Up to 6 files for this campaign, such as a partner's logo or the brief as a PDF. Each is `{"source": "<public URL>"}` or `{"data": "<base64>"}`, with a `name`. Pictures (PNG, JPEG, WebP, GIF or SVG), PDFs and text. They're held with the campaign and never added to the library.
`pieces`	number	No	How many pieces, 2 to 16. Defaults to 6. Counts written in the brief ("four posts and two photos") set it when it is left out.
`formats`	array of strings	No	Up to 48 format ids, such as `instagram-post`, `instagram-story`, `linkedin-landscape` or `email-header`, or platform ids such as `instagram`, whose formats the plan chooses from the brief. Left out, the channels the brief names hold the plan to their formats, or with none named the plan picks. An unknown id is refused with the full list.
`kinds`	array of `design`, `image`, `video`	No	What the pieces may be made as. Defaults to all three where generation is on and the role may add to the library. The plan picks the mix, with at most 3 videos.
`latitude`	string: `brand`, `first` or `free`	No	How far the materials may stretch past what the brand owns, as on Create. Defaults to `brand`.
`photos`	boolean	No	Allow up to 2 new photographs, made once and shared by every piece. Defaults to `false`.
`make`	string	No	A campaign `id` whose plan the person has said yes to: make every piece as planned. Pass it on its own.
`discard`	string	No	A campaign `id` whose plan the person doesn't want: drop it. Pass it on its own.
`check`	string	No	The `id` an earlier call returned, to see how the pieces are getting on. Pass it on its own.

Every campaign stops at its plan. The first call waits for the plan (about a minute) and returns it with status review: the idea, the line, the look, any notes, each piece's title, kind, format and brief, and a reviewUrl. Nothing is made yet. The agent shows the person the plan and, once they say yes, calls again with make. The person can also edit the plan at the reviewUrl and press Make all there.

Pieces take a few minutes, so the agent calls with check until status is ready. Each ready design has a previewUrl picture and each image or video a fileUrl, both to show the person, plus an openUrl. The reviewUrl opens the whole campaign in Archetype to edit and download. See Campaigns.

Example

{ "brief": "Launch our spring range on Instagram: three posts and a story, sale ends 15 May", "latitude": "first" }

After the person approves the plan

{ "make": "<campaign id>" }

update_brand

Changes one item in the brand per call, only when the person asked for that change. It needs a connection approved with Change the brand when you ask it to, and the person's role must allow edits in that area. By default the change becomes a draft that waits for review. See Changes from agents.

Argument	Type	Required	What it does
`domain`	string: `tokens`, `voice`, `info`, `assets`, `files`, `icons`, `components`, `artifacts`, `templates`, `designs`	Yes, unless `undo`, `apply` or `discard`	What kind of thing to change. `designs` saves a document made from a template's pages (create only).
`handle`	string	No	Which item: a token path (`color.brand.500`, or `modes`), a voice slug, a logo name, a file name, an icon set slug, a component key, an artifact handle or a template key. Not used for `info`.
`example`	string	No	`components` only. The example to edit, add or delete, by name, such as `Primary · Hover`.
`icon`	string	No	`icons` only. An icon's key within a custom set.
`frame`	string or number	No	`templates` only. The frame to edit or delete, by name or number from 1, or the new frame's name with `create`.
`value`	any	No	What the item becomes: a bare value (a hex, a number of px, a family name) or an object of only the fields to change. Artwork goes in as `{source}`, `{svg}` or `{data}`.
`find`	string	No	Exact text to change in a voice document, a component example, an artifact's code or a template frame. Must occur exactly once.
`replace`	string	No	What `find` becomes. `""` removes it.
`create`	boolean	No	Add a new item at `handle`.
`delete`	boolean	No	Remove the item at `handle`. It can be put back with `undo`.
`import`	object	No	`tokens`, `components` or `icons`: many items in one call, from `{"source": "<https URL>"}` or `{"document": ...}`. `"dryRun": true` previews.
`apply`	string	No	A draft id: make that change for real, only after the person said yes. Pass it on its own.
`discard`	string	No	A draft id: drop it. Pass it on its own.
`replaces`	string	No	A pending draft id this call revises.
`undo`	string or object	No	A `changeId`, `"last"`, or `{"since": "<changeId>"}` for that change and every later one you made. Pass it on its own.

Example

{ "domain": "tokens", "handle": "color.brand.500", "value": "#2179ef" }

The exact value shape for every domain, and the limits, are in get_brand with {"domain": "schema"}. A few shapes worth knowing:

Font files. typography.<family> takes {"fonts": [...]} to upload the family's files, each as {"source": "<https URL>"} or {"data": "<base64>", "name": "<file name>"}. Files are .woff2, .woff, .ttf or .otf, at most 3 MB each and 24 a call (1.5 MB each sent as data). Weight and style come from the file name unless given, and an upload replaces only the file at its weight and style. Font files are licensed, so an agent should ask before uploading them.
When to use and guidance. Logos, icon sets and artifacts take whenToUse as short tags of at most 40 characters, such as "Dark background", and guidance as free text for sentences such as sizes and pairings. A sentence sent as a tag is refused.
How a photo fits its slot. In a template's bindings or a design's slots, a file binding takes "fit": "fill" covers the box (the default for a photo), "fit" shows the whole picture inside it, and "tile" repeats it. With "fill", "focus": {"x": 50, "y": 20} keeps that point in view; with "tile", "size" is a tile's width in percent of the box.

Upload font files

{ "domain": "tokens", "handle": "typography.gt-walsheim", "value": { "fonts": [{ "source": "https://example.com/GT-Walsheim-Bold.woff2", "weight": 700 }] } }

Fit a photo in a template slot

{ "domain": "templates", "handle": "launch-post", "frame": 1, "value": { "bindings": { "hero": { "file": "team-offsite.jpg", "fit": "fill", "focus": { "x": 50, "y": 30 } } } } }

Older tool names

Before version 3 the server published one tool per domain, such as get_brand_tokens and get_brand_components. Those names still answer and map to the matching get_brand domain, but they are no longer listed. Use get_brand.

Resources and limits

For clients that prefer MCP resources, the server also lists archetype://context (the brief), archetype://tokens (DTCG JSON), and one resource per voice document, artifact, component and icon set.

Each person can make up to 240 calls a minute to a brand, and a brand takes up to 20,000 calls a day.

Connect an agentAdd the server to your client and approve it.Changes from agentsHow update_brand drafts are reviewed and applied.CampaignsWhat create_campaign makes, and how the plan is reviewed.

Something missing or wrong on this page? Write to support@heyarchetype.com.