How to Set Up the Stitch MCP Server for Agent Environment Integration

The Stitch MCP server acts as a bridge between AI agents and the Stitch design-to-code ecosystem, exposing tools like get_screen and list_projects that agents discover via the list_tools RPC and invoke using a namespaced prefix such as mcp_stitch:.

The google-labs-code/stitch-skills repository enables AI agents to interact with Stitch projects through the Model-Control-Protocol (MCP). Setting up the Stitch MCP server for your agent environment requires configuring endpoint URLs, authentication credentials, and verifying that the agent can discover the available tool namespace before invoking any design-to-code operations.

Stitch MCP Architecture Overview

The integration relies on four core components that handle discovery, execution, data storage, and authentication.

Stitch MCP Server

The Stitch MCP Server is a lightweight HTTP/gRPC service that implements the MCP tool contracts for Stitch. It reads local Stitch project files stored under .stitch/ (such as designs/*.html and designs/*.md) and returns them as base-64-encoded payloads. Agents interact with this server remotely, avoiding direct filesystem access.

Agent Runtime

The Agent Runtime executes skill logic defined in repository SKILL.md files. According to the implementation in /plugins/stitch-utilities/skills/stitch-loop/SKILL.md, each skill begins with a namespace discovery step using list_tools, followed by invocations of the appropriate MCP tool (e.g., mcp_stitch:get_screen).

Stitch Project Files

Stitch projects store screens and design markup in the .stitch/ directory. When an agent calls get_screen, the MCP server reads the screen's source HTML, encodes it in base-64, and returns it in the screenHtmlBase64 field of the JSON response.

Credential Store

The MCP server requires an API key and endpoint URL, supplied via environment variables or a JSON configuration file. The Upload to Stitch skill outlines the specific method for retrieving the key from configuration files in /plugins/stitch-design/skills/upload-to-stitch/SKILL.md.

Prerequisites and Configuration

Before agents can invoke Stitch tools, you must install the server and expose the correct environment variables.

Install the MCP Server

Follow the official Google Stitch MCP setup guide at https://stitch.withgoogle.com/docs/mcp/setup/ to install the binary or container.

Configure Environment Variables

Set the following variables in your agent environment:

• STITCH_MCP_URL: The server endpoint (default: http://localhost:8080).
• STITCH_MCP_API_KEY: The API key generated from the Stitch console.

As noted in /README.md, these skills explicitly require a configured MCP server before invocation.

Validating the MCP Connection

Verify that the agent can reach the server and discover the Stitch tool namespace.

Discover Available Tools

Send a GET request to the /list_tools endpoint to retrieve the tool prefix:

export STITCH_MCP_URL=http://localhost:8080
export STITCH_MCP_API_KEY=YOUR_API_KEY

curl -H "Authorization: Bearer $STITCH_MCP_API_KEY" \
  $STITCH_MCP_URL/list_tools

A successful response returns a JSON array containing tools prefixed with mcp_stitch:, such as mcp_stitch:get_screen and mcp_stitch:list_projects.

Implementing Agent-Side MCP Calls

Once validated, implement the discovery and invocation pattern in your agent code.

Python Implementation

The following Python example demonstrates namespace discovery and screen retrieval:

import os
import base64
import requests

MCP_URL = os.getenv("STITCH_MCP_URL", "http://localhost:8080")
API_KEY = os.getenv("STITCH_MCP_API_KEY", "")

def list_tools():
    """Discover available MCP tools and return the Stitch prefix."""
    resp = requests.get(
        f"{MCP_URL}/list_tools",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    return resp.json()  # e.g., {"tools": ["mcp_stitch:get_screen", ...]}

def get_screen(screen_id):
    """Fetch and decode a screen's HTML by ID."""
    payload = {"screenId": screen_id}
    resp = requests.post(
        f"{MCP_URL}/mcp_stitch:get_screen",
        json=payload,
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    data = resp.json()
    html_b64 = data["screenHtmlBase64"]
    return base64.b64decode(html_b64).decode("utf-8")

if __name__ == "__main__":
    tools = list_tools()
    prefix = [t.split(":")[0] for t in tools["tools"] if "stitch" in t][0]
    print("Discovered MCP prefix:", prefix)
    html = get_screen("home")
    print(html[:200])  # Display first 200 characters

Shell Validation

For quick debugging, fetch a specific screen via command line:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STITCH_MCP_API_KEY" \
  -d '{"screenId":"home"}' \
  $STITCH_MCP_URL/mcp_stitch:get_screen | jq .

Skill Integration Patterns

Real-world skills in the repository follow a consistent discovery-to-execution flow.

The Stitch-Loop Skill Workflow

The stitch-loop skill in /plugins/stitch-utilities/skills/stitch-loop/SKILL.md provides a concrete implementation:

1. Discovery: Call list_tools to extract the mcp_stitch: prefix.
2. Enumeration: Invoke mcp_stitch:list_projects to retrieve available projects.
3. Retrieval: Call mcp_stitch:get_screen with a specific screenId.
4. Processing: Decode the base64 HTML and optionally render via Chrome DevTools MCP.

Additional skills such as design-md (/plugins/stitch-utilities/skills/design-md/SKILL.md) and react-vite-dashboard (/plugins/stitch-build/skills/react-vite-dashboard/SKILL.md) reference these same MCP discovery steps and JSON structures defined in /plugins/stitch-build/skills/react-components/resources/stitch-api-reference.md.

Summary

• The Stitch MCP server exposes design-to-code tools via HTTP/gRPC, preventing agents from requiring direct filesystem access to .stitch/ directories.
• Environment variables STITCH_MCP_URL and STITCH_MCP_API_KEY authenticate and locate the server.
• Discovery protocol requires agents to call list_tools first to obtain the mcp_stitch: namespace prefix before invoking specific tools like get_screen or upload_design_md.
• Base64 encoding is used for all screen HTML payloads returned by the server.
• Validation can be performed via shell commands or Python requests to ensure the agent environment is correctly configured before executing complex skills.

Frequently Asked Questions

What is the default URL for the Stitch MCP server?

The default endpoint is http://localhost:8080, configurable via the STITCH_MCP_URL environment variable.

How does an agent discover available Stitch tools?

Agents must call the list_tools RPC endpoint, which returns a JSON list including tools prefixed with mcp_stitch:. The agent extracts this prefix to construct subsequent tool calls like mcp_stitch:get_screen.

Where does the MCP server read project files from?

The server reads Stitch project files from the local .stitch/ directory, specifically designs/*.html and designs/*.md, encoding content in base-64 before returning it to the agent.

Which repository skills require the MCP server?

According to /README.md and skill documentation such as /plugins/stitch-design/skills/upload-to-stitch/SKILL.md, any skill performing design retrieval, project listing, or screen generation requires the MCP server to be running and accessible before skill invocation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}