Reference
| # | Tool | Category | Read-Only |
|---|---|---|---|
| 1 | create_project | Project Management | false |
| 2 | get_project | Project Management | true |
| 3 | list_projects | Project Management | true |
| 4 | list_screens | Screen Management | true |
| 5 | get_screen | Screen Management | true |
| 6 | generate_screen_from_text | AI Generation | false |
| 7 | edit_screens | AI Generation | false |
| 8 | generate_variants | AI Generation | false |
| 9 | create_design_system | Design Systems | false |
| 10 | update_design_system | Design Systems | false |
| 11 | list_design_systems | Design Systems | true |
| 12 | apply_design_system | Design Systems | false |
| 13 | upload_design_md | Design Systems | false |
| 14 | create_design_system_from_design_md | Design Systems | false |
Tools
create_project
Creates a new Stitch project. A project is a container for UI designs and frontend code.
Annotations
destructive
Input
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Optional. The title of the project."
}
},
"required": []
}
Output
Returns the created Project resource with generated name, title, and metadata.
Example Prompts
get_project
Retrieves the details of a specific Stitch project using its project name.
Annotations
readOnly
Input
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Required. Resource name. Format: `projects/{project}`. Example: `projects/4044680601076201931`"
}
},
"required": ["name"]
}
Output
Returns a Project resource object.
Example Prompts
list_projects
Lists all Stitch projects accessible to the user. By default, it lists projects owned by the user.
Annotations
readOnly
Input
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "Optional. AIP-160 filter on `view` field. Supported: `view=owned` (default), `view=shared`."
}
},
"required": []
}
Output
Array of Project resource objects.
Example Prompts
list_screens
Lists all screens within a given Stitch project.
Annotations
readOnly
Input
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Required. Project ID (e.g., '4044680601076201931'), without `projects/` prefix."
}
},
"required": ["projectId"]
}
Output
Array of Screen objects.
Example Prompts
get_screen
Retrieves the details of a specific screen within a project.
Annotations
readOnly
Input
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Required. Resource name. Format: `projects/{project}/screens/{screen}`"
},
"projectId": {
"type": "string",
"description": "Required (deprecated). Project ID without prefix."
},
"screenId": {
"type": "string",
"description": "Required (deprecated). Screen ID without prefix."
}
},
"required": ["name", "projectId", "screenId"]
}
projectIdandscreenIdare deprecated in favor ofname(resource name format), but all three are currently required.
Output
Returns a Screen object with htmlCode, screenshot, figmaExport file references and download URLs.
Example Prompts
generate_screen_from_text
Generates a new screen from a text prompt. This process normally takes a few minutes. Avoid retrying even when you encounter connection errors. Connection errors don’t necessarily mean failure, try using get_screen after a few minutes. If output_components contains suggestions, present them to the user. If accepted, call again with the suggestion as the new prompt.
Annotations
destructive
Input
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Required. Project ID without prefix."
},
"prompt": {
"type": "string",
"description": "Required. Text prompt describing the screen to generate."
},
"deviceType": {
"type": "string",
"enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"]
},
"modelId": {
"type": "string",
"enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"]
}
},
"required": ["projectId", "prompt"]
}
GEMINI_3_PROis deprecated. UseGEMINI_3_1_PROorGEMINI_3_FLASHinstead.
Output
Returns generated Screen objects and SessionOutputComponent entries (text, suggestions, or design references).
Example Prompts
edit_screens
Edits existing screens using a text prompt. Similar to generate_screen_from_text, this process normally takes a few minutes. Avoid retrying even when you encounter connection errors. Connection errors don’t necessarily mean failure, try using get_screen after a few minutes.
Annotations
destructive
Input
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Required. Project ID without prefix."
},
"selectedScreenIds": {
"type": "array",
"items": { "type": "string" },
"description": "Required. Screen IDs to edit, without `screens/` prefix."
},
"prompt": {
"type": "string",
"description": "Required. Edit instruction."
},
"deviceType": {
"type": "string",
"enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"]
},
"modelId": {
"type": "string",
"enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"]
}
},
"required": ["projectId", "selectedScreenIds", "prompt"]
}
GEMINI_3_PROis deprecated. UseGEMINI_3_1_PROorGEMINI_3_FLASHinstead.
Output
Returns the updated Screen objects.
Example Prompts
generate_variants
Generates design variants of existing screens.
Annotations
destructive
Input
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Required. Project ID without prefix."
},
"selectedScreenIds": {
"type": "array",
"items": { "type": "string" },
"description": "Required. Screen IDs to generate variants for."
},
"prompt": {
"type": "string",
"description": "Required. Text guiding variant generation."
},
"variantOptions": {
"$ref": "#/$defs/VariantOptions",
"description": "Required. Variant configuration."
},
"deviceType": {
"type": "string",
"enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"]
},
"modelId": {
"type": "string",
"enum": ["MODEL_ID_UNSPECIFIED", "GEMINI_3_PRO", "GEMINI_3_FLASH", "GEMINI_3_1_PRO"]
}
},
"required": ["projectId", "selectedScreenIds", "prompt", "variantOptions"]
}
GEMINI_3_PROis deprecated. UseGEMINI_3_1_PROorGEMINI_3_FLASHinstead.
VariantOptions
{
"type": "object",
"properties": {
"variantCount": {
"type": "integer",
"description": "Number of variants (1–5). Default: 3."
},
"creativeRange": {
"type": "string",
"enum": ["CREATIVE_RANGE_UNSPECIFIED", "REFINE", "EXPLORE", "REIMAGINE"]
},
"aspects": {
"type": "array",
"items": {
"type": "string",
"enum": ["VARIANT_ASPECT_UNSPECIFIED", "LAYOUT", "COLOR_SCHEME", "IMAGES", "TEXT_FONT", "TEXT_CONTENT"]
}
}
}
}
Output
Returns generated variant Screen objects.
Example Prompts
create_design_system
Creates a new design system for a project. Establishes foundational design tokens (colors, typography, shapes, appearance) that apply across all screens.
Annotations
destructive
Input
{
"type": "object",
"properties": {
"designSystem": {
"$ref": "#/$defs/DesignSystem",
"description": "Required. The design system to create."
},
"projectId": {
"type": "string",
"description": "Optional. Project ID. If empty, creates a global (unassociated) asset."
}
},
"required": ["designSystem"]
}
DesignSystem
{
"type": "object",
"properties": {
"displayName": {
"type": "string",
"description": "Required. Display name."
},
"theme": {
"$ref": "#/$defs/DesignTheme",
"description": "Required. Theme configuration."
}
},
"required": ["displayName", "theme"]
}
DesignTheme
{
"type": "object",
"properties": {
"colorMode": { "type": "string", "enum": ["COLOR_MODE_UNSPECIFIED", "LIGHT", "DARK"] },
"headlineFont": { "type": "string", "enum": ["FONT_UNSPECIFIED", "INTER", "DM_SANS", "GEIST", "..."] },
"bodyFont": { "type": "string", "enum": ["FONT_UNSPECIFIED", "INTER", "DM_SANS", "GEIST", "..."] },
"labelFont": { "type": "string", "enum": ["FONT_UNSPECIFIED", "INTER", "DM_SANS", "GEIST", "..."] },
"roundness": { "type": "string", "enum": ["ROUNDNESS_UNSPECIFIED", "ROUND_FOUR", "ROUND_EIGHT", "ROUND_TWELVE", "ROUND_FULL"] },
"customColor": { "type": "string", "description": "Required. Hex color seed for the dynamic color system." },
"colorVariant": { "type": "string", "enum": ["COLOR_VARIANT_UNSPECIFIED", "MONOCHROME", "NEUTRAL", "TONAL_SPOT", "VIBRANT", "EXPRESSIVE", "FIDELITY", "CONTENT", "RAINBOW", "FRUIT_SALAD"] },
"overridePrimaryColor": { "type": "string", "description": "Optional. Override primary color (hex)." },
"overrideSecondaryColor": { "type": "string", "description": "Optional. Override secondary color (hex)." },
"overrideTertiaryColor": { "type": "string", "description": "Optional. Override tertiary color (hex)." },
"overrideNeutralColor": { "type": "string", "description": "Optional. Override neutral color (hex)." },
"designMd": { "type": "string", "description": "Optional. Markdown design instructions." }
},
"required": ["colorMode", "headlineFont", "bodyFont", "roundness", "customColor"]
}
Output
Returns the created design system Asset.
Example Prompts
update_design_system
Updates an existing design system. Identifies the asset by its name field.
Annotations
destructive
Input
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Required. Resource name. Format: `assets/{asset}`. Example: `assets/15996705518239280238`"
},
"projectId": {
"type": "string",
"description": "Required. Project ID without prefix."
},
"designSystem": {
"$ref": "#/$defs/DesignSystem",
"description": "Required. The updated design system content."
}
},
"required": ["name", "projectId", "designSystem"]
}
Uses the same
DesignSystemandDesignThemeschemas ascreate_design_system.
Output
Returns the updated design system Asset.
Example Prompts
list_design_systems
Lists all design systems for a project (or global design systems if no projectId).
Annotations
readOnly
Input
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Optional. Project ID. If empty, lists global design systems."
}
},
"required": []
}
Output
Array of Asset objects containing design systems.
Example Prompts
apply_design_system
Applies a design system to one or more screens, modifying their appearance to match the system’s tokens (colors, fonts, shapes).
Annotations
destructive
Input
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Required. Project ID without prefix."
},
"selectedScreenInstances": {
"type": "array",
"items": { "$ref": "#/$defs/SelectedScreenInstance" },
"description": "Required. Screen instances to update (from `get_project`)."
},
"assetId": {
"type": "string",
"description": "Required. Design system asset ID (from `list_design_systems`), without `assets/` prefix."
}
},
"required": ["projectId", "selectedScreenInstances", "assetId"]
}
SelectedScreenInstance
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Required. The screen instance ID (NOT the source screen ID). Available from `get_project`."
},
"sourceScreen": {
"type": "string",
"description": "Required. Resource name. Format: `projects/{project}/screens/{screen}`"
}
},
"required": ["id", "sourceScreen"]
}
Output
Returns the updated Screen objects.
Example Prompts
upload_design_md
Uploads a DESIGN.md file to a Stitch project. This is the first step in the two-step DESIGN.md workflow. After uploading, call create_design_system_from_design_md to create the design system.
Annotations
destructive
Input
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Required. Project ID (e.g., '4044680601076201931'), without `projects/` prefix."
},
"designMdBase64": {
"type": "string",
"description": "Required. Base64-encoded DESIGN.md content. The decoded content must be valid UTF-8."
}
},
"required": ["projectId", "designMdBase64"]
}
Output
Returns a screen instance object representing the uploaded DESIGN.md. The id and sourceScreen fields from this response are required as input to create_design_system_from_design_md.
Example Prompts
create_design_system_from_design_md
Creates a design system from an uploaded DESIGN.md file and displays it in the UI. Must be called after upload_design_md.
Annotations
destructive
Input
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Required. Project ID without prefix."
},
"selectedScreenInstance": {
"$ref": "#/$defs/SelectedScreenInstance",
"description": "Required. The screen instance created by `upload_design_md`."
},
"deviceType": {
"type": "string",
"enum": ["DEVICE_TYPE_UNSPECIFIED", "MOBILE", "DESKTOP", "TABLET", "AGNOSTIC"],
"description": "Optional. The device type for the design system."
}
},
"required": ["projectId", "selectedScreenInstance"]
}
Uses the same
SelectedScreenInstanceschema asapply_design_system.
Output
Returns a DesignSystem with an assetId that can be used with apply_design_system.
Example Prompts
Shared Types
Screen
A generated screen design within a Stitch project.
| Field | Type | Description |
|---|---|---|
name | string | Resource name. Format: projects/{project}/screens/{screen} |
id | string | (Deprecated) The screen id. |
title | string | Title of the screen. |
prompt | string | Prompt used to generate the screen. |
screenshot | File | Screenshot image of the screen. |
htmlCode | File | HTML code of the screen. |
figmaExport | File | Figma export of the screen. |
theme | DesignTheme | Theme used for generation. |
deviceType | DeviceType | Device type. |
screenType | ScreenType | Screen type. |
screenMetadata | ScreenMetadata | Metadata (agent, status, display mode). |
width | string | Width of the screen. |
height | string | Height of the screen. |
groupId | string | Group id for related screens (e.g., variants). |
groupName | string | Display name of the group. |
generatedBy | string | Generator identifier. |
isCreatedByClient | boolean | true if created via API upload, false if by agents. |
File
| Field | Type | Description |
|---|---|---|
name | string | Resource name. Format: projects/{project}/files/{file} |
downloadUrl | string | URL for download. FIFE base URL for images. |
mimeType | string | E.g., "image/png", "text/html". |
fileContentBase64 | string | (Write-only) Base64-encoded content for uploads. |
uploadBlobId | string | BlobId from upload service. |
userFeedback | UserFeedback | (Read-only) Latest feedback. |
DesignSystem
Represents visual/functional design guidelines used to generate consistent, branded designs.
| Field | Type | Description |
|---|---|---|
displayName | string | Display name of the design system. |
theme | DesignTheme | Theme configuration. |
Asset
Wrapper for design system resources (used by update_design_system).
| Field | Type | Description |
|---|---|---|
name | string | Resource name. Format: assets/{asset} |
designSystem | DesignSystem | The design system content. |
version | string | (Read-only) Version counter. 0 = unversioned. |
DesignTheme
| Field | Type | Required | Description |
|---|---|---|---|
colorMode | ColorMode | true | Light or dark mode. |
headlineFont | Font | true | Headline typography. |
bodyFont | Font | true | Body typography. |
labelFont | Font | false | Label typography. |
roundness | Roundness | true | Corner roundness. |
customColor | string | true | Seed color for dynamic color system (hex, e.g., "#ff0000"). |
colorVariant | ColorVariant | false | Dynamic color system variant. |
overridePrimaryColor | string | false | Override primary color (hex). |
overrideSecondaryColor | string | false | Override secondary color (hex). |
overrideTertiaryColor | string | false | Override tertiary color (hex). |
overrideNeutralColor | string | false | Override neutral color (hex). |
designMd | string | false | Markdown design instructions. |
ScreenMetadata
| Field | Type | Description |
|---|---|---|
agentType | AgentTypeEnum | TURBO_AGENT, PRO_AGENT, IMAGE_AGENT, GENIE_AGENT, IMAGE_PRO_AGENT, HATTER_AGENT, GEMINI_3_AGENT |
status | ScreenStatusEnum | IN_PROGRESS, COMPLETE, FAILED |
statusMessage | string | Human-readable status from agent. |
displayMode | DisplayModeEnum | SCREENSHOT, HTML, CODE, MARKDOWN, STICKY_NOTE |
isRemixed | boolean | Whether screen was created from a remix. |
componentRegions | ComponentRegion[] | Component region annotations. |
SessionOutputComponent
Returned from generation tools in output_components.
| Field | Type | Description |
|---|---|---|
text | string | Agent text response. |
suggestion | string | Suggested follow-up for the user. |
design | Design | Generated design reference. |
UserFeedback
| Field | Type | Description |
|---|---|---|
rating | string | POSITIVE or NEGATIVE. |
comment | string | Additional comment. |
designFeedbackReason | string | DESIGN_DOESNT_MATCH_PROMPT, EDIT_DOESNT_MATCH_PROMPT, COMPONENT_ISSUE, INCORRECT_THEME, etc. |
VariantOptions
| Field | Type | Description |
|---|---|---|
variantCount | integer | Variants to generate (1–5). Default: 3. |
creativeRange | CreativeRange | Creative freedom level. |
aspects | VariantAspect[] | Aspects to focus on. |
SelectedScreenInstance
Used by apply_design_system and create_design_system_from_design_md.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | true | Screen instance ID (from get_project), not the source screen ID. |
sourceScreen | string | true | Resource name. Format: projects/{project}/screens/{screen} |
Enums
DeviceType Enum
| Value | Description |
|---|---|
DEVICE_TYPE_UNSPECIFIED | Unspecified. |
MOBILE | Mobile device. |
DESKTOP | Desktop device. |
TABLET | Tablet device. |
AGNOSTIC | Not tied to a device. |
ModelId Enum
| Value | Description |
|---|---|
MODEL_ID_UNSPECIFIED | Unspecified. |
GEMINI_3_PRO | (Deprecated) Gemini 3 Pro. Use GEMINI_3_1_PRO or GEMINI_3_FLASH instead. |
GEMINI_3_FLASH | Gemini 3 Flash. |
GEMINI_3_1_PRO | Gemini 3.1 Pro. |
ScreenType Enum
| Value | Description |
|---|---|
SCREEN_TYPE_UNSPECIFIED | Defaults to DESIGN. |
DESIGN | A design screen. |
IMAGE | A pure image. |
PROTOTYPE | A design prototype. |
DOCUMENT | A document (e.g., PRD). |
PROTOTYPE_V2 | A design prototype v2. |
ColorMode Enum
| Value | Description |
|---|---|
COLOR_MODE_UNSPECIFIED | Unspecified. |
LIGHT | Light mode. |
DARK | Dark mode. |
ColorVariant Enum
| Value | Description |
|---|---|
COLOR_VARIANT_UNSPECIFIED | Unspecified. |
MONOCHROME | Monochrome variant. |
NEUTRAL | Neutral variant. |
TONAL_SPOT | Tonal spot variant. |
VIBRANT | Vibrant variant. |
EXPRESSIVE | Expressive variant. |
FIDELITY | Fidelity variant. |
CONTENT | Content variant. |
RAINBOW | Rainbow variant. |
FRUIT_SALAD | Fruit salad variant. |
Font Enum
29 supported font families:
INTER · DM_SANS · GEIST · SORA · MANROPE · LEXEND · EPILOGUE · BE_VIETNAM_PRO · PLUS_JAKARTA_SANS · PUBLIC_SANS · SPACE_GROTESK · SPLINE_SANS · WORK_SANS · MONTSERRAT · METROPOLIS · SOURCE_SANS_THREE · NUNITO_SANS · ARIMO · HANKEN_GROTESK · RUBIK · IBM_PLEX_SANS · NEWSREADER · NOTO_SERIF · DOMINE · LIBRE_CASLON_TEXT · EB_GARAMOND · LITERATA · SOURCE_SERIF_FOUR
Roundness Enum
| Value | Description |
|---|---|
ROUNDNESS_UNSPECIFIED | Unspecified. |
ROUND_TWO | (Deprecated) Round 2. |
ROUND_FOUR | Round 4. |
ROUND_EIGHT | Round 8. |
ROUND_TWELVE | Round 12. |
ROUND_FULL | Fully rounded. |
CreativeRange Enum
| Value | Description |
|---|---|
CREATIVE_RANGE_UNSPECIFIED | Unspecified. |
REFINE | Subtle refinements, close to original. |
EXPLORE | Balanced exploration. (Default) |
REIMAGINE | Radical explorations. |
VariantAspect Enum
| Value | Description |
|---|---|
VARIANT_ASPECT_UNSPECIFIED | Unspecified. |
LAYOUT | Element arrangement. |
COLOR_SCHEME | Color palette. |
IMAGES | Image usage. |
TEXT_FONT | Font choices. |
TEXT_CONTENT | Text content. |
MCP Annotations
MCP Annotations are metadata hints that an MCP server attaches to each tool definition to tell the client (the AI agent or host application) about the tool’s behavioral characteristics. They’re part of the MCP spec and help clients make smarter decisions about tool usage without needing to understand the tool’s implementation.
Each tool includes behavior annotations:
| Annotation | Meaning |
|---|---|
readOnlyHint | true = read-only, no mutations. |
destructiveHint | true = may create/modify/delete resources. |
idempotentHint | true = repeated calls produce same result. |
openWorldHint | true = interacts with external systems. |
How they work with tools in practice
Each tool in the Stitch MCP server declares these as part of its tool registration. For example:
list_projectshasreadOnlyHint: true— it just fetches data, so an agent can call it without worrying about side effects.create_projecthasreadOnlyHint: false,destructiveHint: true,idempotentHint: false— it mutates state, so the client should confirm with the user first.generate_screen_from_texthasdestructiveHint: trueandidempotentHint: false— each call creates a new screen, so retrying on a timeout could produce duplicates.
Why they matter
These are hints, not enforced rules. They allow MCP clients to:
- Auto-approve read-only tools without prompting the user
- Show confirmation dialogs for destructive operations
- Safely retry idempotent tools on network failures
- Audit external interactions when
openWorldHintis true
In the Stitch server’s case, all tools have openWorldHint: false because they interact only with the Stitch backend — not arbitrary third-party services.
Original: https://stitch.withgoogle.com/docs/mcp/reference/
Translated from the official Google Stitch documentation. Original content © Google LLC. This is an independent, unofficial translation.