Reference

Installation

npm install @google/stitch-sdk

Exports

All exports are available from @google/stitch-sdk:

import {
  stitch,           // Default singleton instance
  Stitch,           // Domain class: project management
  Project,          // Domain class: screen management within a project
  Screen,           // Domain class: screen operations
  StitchToolClient, // Low-level MCP client
  StitchProxy,      // Local proxy server
  StitchError,      // Error class
  StitchErrorCode,  // Error code enum
} from "@google/stitch-sdk";

AI SDK adapter (separate subpath):

import { stitchTools } from "@google/stitch-sdk/ai";

---

stitch (Singleton)

The default entry point. A lazily-initialized Proxy that combines Stitch domain methods and StitchToolClient infrastructure methods.

Reads STITCH_API_KEY and STITCH_HOST from environment variables on first access.

import { stitch } from "@google/stitch-sdk";

Domain methods

Method	Returns	Description
createProject(title)	Promise<Project>	Creates a new project.
projects()	Promise<Project[]>	Lists all projects accessible to the authenticated user.
project(id)	Project	Creates a Project handle from an existing project ID or resource name. No API call.

Infrastructure methods

Method	Returns	Description
listTools()	Promise<{ tools: ToolDefinition[] }>	Lists all available MCP tools.
callTool<T>(name, params)	Promise<T>	Calls a raw MCP tool by name.
close()	Promise<void>	Closes the underlying MCP client connection.

---

Stitch

Main entry point class. Manages projects.

import { Stitch, StitchToolClient } from "@google/stitch-sdk";

const client = new StitchToolClient({ apiKey: "..." });
const s = new Stitch(client);

Constructor

Parameter	Type	Description
client	StitchToolClient	An initialized tool client instance.

Methods

Method	Returns	Description
createProject(title)	Promise<Project>	Creates a new project. Maps to MCP tool create_project.
projects()	Promise<Project[]>	Lists all projects. Maps to MCP tool list_projects.
project(id)	Project	Creates a Project handle without an API call. Accepts a project ID or full resource name (projects/{id}).

---

Project

A Stitch project containing screens.

Properties

Property	Type	Description
projectId	string	The project ID (without projects/ prefix).
id	string	Alias for projectId.
data	any	Raw API response data, if constructed from server response. undefined if constructed from an ID string.

Methods

Method	Parameters	Returns	Description
generate(prompt, deviceType?, modelId?)	prompt: string, deviceType?: DeviceType, modelId?: ModelId	Promise<Screen>	Generates a new screen from a text prompt. Maps to generate_screen_from_text.
screens()	-	Promise<Screen[]>	Lists all screens in the project. Maps to list_screens.
getScreen(screenId)	screenId: string	Promise<Screen>	Retrieves a specific screen by ID. Maps to get_screen.
upload(filePath, opts?)	filePath: string, opts?: { title?: string, createScreenInstances?: boolean }	Promise<UploadResult>	Uploads a file (.png, .jpg, .jpeg, .webp, .html, .htm) and creates a screen. Posts directly to REST API. Never throws — returns a discriminated result.
createDesignSystem(ds)	ds: { displayName: string }	Promise<DesignSystem>	Creates a design system for this project.
listDesignSystems()	-	Promise<DesignSystem[]>	Lists all design systems in the project.
designSystem(id)	id: string	DesignSystem	Creates a DesignSystem handle from an asset ID. No API call.
uploadDesignMd(designMdBase64)	designMdBase64: string	Promise<any>	Uploads a DESIGN.md file (base64-encoded) to the project. Returns a screen instance. Maps to upload_design_md.
createDesignSystemFromDesignMd(selectedScreenInstance, deviceType?)	selectedScreenInstance: SelectedScreenInstance, deviceType?: DeviceType	Promise<DesignSystem>	Creates a design system from an uploaded DESIGN.md. Maps to create_design_system_from_design_md.

---

DesignSystem

A design system asset that defines visual tokens for a project.

Properties

Property	Type	Description
id	string	The asset ID.
data	any	Raw API response data. undefined if constructed from an ID string.

Methods

Method	Parameters	Returns	Description
update(ds)	ds: { displayName?: string }	Promise<DesignSystem>	Updates the design system’s metadata.
apply(selectedScreenInstances)	{ id: string, sourceScreen: string }[]	Promise<Screen[]>	Applies this design system to the given screens. Only pass id and sourceScreen — extra fields cause errors.

---

Screen

A generated UI screen. Provides access to HTML code and screenshot images.

Properties

Property	Type	Description
projectId	string	Parent project ID.
screenId	string	The screen ID.
id	string	Alias for screenId.
data	any	Raw API response data.

Methods

Method	Parameters	Returns	Description
edit(prompt, deviceType?, modelId?)	prompt: string, deviceType?: DeviceType, modelId?: ModelId	Promise<Screen>	Edits this screen with a text prompt. Returns a new Screen; original is unchanged. Maps to edit_screens.
variants(prompt, variantOptions, deviceType?, modelId?)	prompt: string, variantOptions: VariantOptions, deviceType?: DeviceType, modelId?: ModelId	Promise<Screen[]>	Generates design variants. Maps to generate_variants.
getHtml()	-	Promise<string>	Returns the HTML download URL for this screen. Uses cached URL if available.
getImage()	-	Promise<string>	Returns the screenshot download URL. Uses cached URL if available.

---

StitchToolClient

Low-level MCP client that connects to the Stitch server over HTTP.

import { StitchToolClient } from "@google/stitch-sdk";

Constructor

Parameter	Type	Description
config	StitchConfigInput	Connection configuration.

StitchConfigInput

Field	Type	Required	Description
apiKey	string	One of apiKey or accessToken	API key for authentication.
accessToken	string	One of apiKey or accessToken	OAuth access token.
projectId	string	Required with accessToken	Google Cloud project ID (for OAuth).
baseUrl	string	No	Override the server URL. Defaults to https://stitch.googleapis.com/mcp.

Methods

Method	Returns	Description
connect()	Promise<void>	Explicitly connects to the MCP server. Called automatically on first tool call.
callTool<T>(name, params)	Promise<T>	Calls a named MCP tool with the given parameters.
listTools()	Promise<{ tools: ToolDefinition[] }>	Lists all available tools from the server.
close()	Promise<void>	Closes the connection.

---

stitchTools(options?)

AI SDK adapter. Returns Stitch tools in Vercel AI SDK format.

Import from the /ai subpath:

import { stitchTools } from "@google/stitch-sdk/ai";

Parameters

Field	Type	Description
options.apiKey	string	Override STITCH_API_KEY env var.
options.include	string[]	Only include specific tool names.

Returns

Record<string, Tool> - Drop directly into generateText({ tools: stitchTools() }).

---

StitchError

Error class thrown by all SDK methods.

Property	Type	Description
message	string	Human-readable error message.
code	StitchErrorCode	Structured error code.

Static methods

Method	Description
StitchError.fromUnknown(error)	Wraps any thrown value into a StitchError.

---

Enums

DeviceType

"DEVICE_TYPE_UNSPECIFIED" | "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC"

ModelId

"MODEL_ID_UNSPECIFIED" | "GEMINI_3_PRO" | "GEMINI_3_FLASH"

CreativeRange

"CREATIVE_RANGE_UNSPECIFIED" | "REFINE" | "EXPLORE" | "REIMAGINE"

VariantAspect

"VARIANT_ASPECT_UNSPECIFIED" | "LAYOUT" | "COLOR_SCHEME" | "IMAGES" | "TEXT_FONT" | "TEXT_CONTENT"

---

Environment Variables

Variable	Description
STITCH_API_KEY	API key for authentication. Used by the stitch singleton and stitchTools().
STITCH_HOST	Override the MCP server URL. Defaults to https://stitch.googleapis.com/mcp.
STITCH_ACCESS_TOKEN	OAuth access token (alternative to API key).
GOOGLE_CLOUD_PROJECT	Google Cloud project ID (required with OAuth).