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

> Integrate your AI agent with the Stitch ecosystem by setting up the Stitch MCP server. Learn how this bridge exposes essential tools for seamless agent interaction.

- Repository: [Google Labs Code/stitch-skills](https://github.com/google-labs-code/stitch-skills)
- Tags: how-to-guide
- Published: 2026-07-18

---

**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`](https://github.com/google-labs-code/stitch-skills/blob/main//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`](https://github.com/google-labs-code/stitch-skills/blob/main//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`](https://github.com/google-labs-code/stitch-skills/blob/main//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:

```bash
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:

```python
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:

```bash
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`](https://github.com/google-labs-code/stitch-skills/blob/main//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`](https://github.com/google-labs-code/stitch-skills/blob/main//plugins/stitch-utilities/skills/design-md/SKILL.md)) and **react-vite-dashboard** ([`/plugins/stitch-build/skills/react-vite-dashboard/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main//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`](https://github.com/google-labs-code/stitch-skills/blob/main//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`](https://github.com/google-labs-code/stitch-skills/blob/main//README.md) and skill documentation such as [`/plugins/stitch-design/skills/upload-to-stitch/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main//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.