# How to Configure the Stitch MCP Server with Environment Variables

> Learn how to configure Stitch MCP server with environment variables. Set STITCH_MCP_URL and STITCH_MCP_API_KEY for seamless authentication across your MCP-enabled skills.

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

---

**Set `STITCH_MCP_URL` and `STITCH_MCP_API_KEY` as environment variables (typically in a `.env` file) to authenticate all MCP-enabled skills with the Stitch server.**

The Stitch MCP server acts as the bridge between Stitch-based skills and the Stitch design platform. According to the `google-labs-code/stitch-skills` source code, every MCP-enabled skill expects the server endpoint and authentication credentials to be supplied via environment variables rather than hardcoded configuration.

## Required Environment Variables

The following variables must be present in the environment when any skill executes an MCP tool call:

| Variable | Purpose | Typical Value |
|----------|---------|---------------|
| `STITCH_MCP_URL` | Base URL of the running MCP server (protocol and port included) | `http://localhost:8080` |
| `STITCH_MCP_API_KEY` | Secret token used to authenticate requests to the MCP server | `sk-...` |
| `STITCH_MCP_PROJECT` | *(Optional)* Default Stitch project ID when none is provided in the prompt | `1234567890` |

## How Skills Consume Environment Configuration

### Upload to Stitch Skill

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), the `upload_to_stitch` MCP tool reads `STITCH_MCP_URL` and `STITCH_MCP_API_KEY` directly from the environment. The skill’s command-line wrapper also accepts `--api-url` and `--api-key` flags, which fall back to the environment variables if omitted.

### Utility Skills

The **design-md** and **stitch-loop** skills ([`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 [`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)) first perform a `list_tools` call to discover the MCP prefix (e.g., `mcp_stitch:`). Once discovered, all subsequent MCP calls automatically inherit the URL and API key from the environment.

### Build Skills

Both the **react-components** and **react-native** build skills ([`plugins/stitch-build/skills/react-components/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-components/SKILL.md) and [`plugins/stitch-build/skills/react-native/SKILL.md`](https://github.com/google-labs-code/stitch-skills/blob/main/plugins/stitch-build/skills/react-native/SKILL.md)) rely on `STITCH_MCP_URL` and `STITCH_MCP_API_KEY` to fetch screen definitions before generating code.

## Step-by-Step Configuration Guide

1. **Start the MCP server** following the official setup guide at [https://stitch.withgoogle.com/docs/mcp/setup/](https://stitch.withgoogle.com/docs/mcp/setup/).

2. **Create a `.env` file** in the root of your project or agent workspace:

   ```dotenv
   # .env

   STITCH_MCP_URL=http://localhost:8080
   STITCH_MCP_API_KEY=sk-REPLACE_WITH_YOUR_KEY
   # Optional: set a default project

   STITCH_MCP_PROJECT=1234567890
   ```

3. **Load the environment** before running skills. Most runtimes (Node.js, Python, or Bash) automatically source `.env` files when using the `dotenv` library or similar loader. Agent runtimes like Codex or Claude typically load this file before invoking any skill.

4. **Verify the configuration** by running an MCP-dependent skill:

   ```bash
   npx skills run stitch::design-md "Analyze project projects/9876"
   ```

   If the server is reachable and the API key is valid, the skill completes successfully; otherwise, you will receive an authentication error indicating a missing or malformed variable.

5. **Troubleshoot common issues**:
   - Ensure the MCP server is listening on the same host and port specified in `STITCH_MCP_URL`.
   - Verify the API key matches the token generated in the MCP dashboard.
   - Remove extra whitespace or quotation marks surrounding values in the `.env` file.

## Summary

- **Configuration is mandatory**: All MCP-enabled skills in `google-labs-code/stitch-skills` require `STITCH_MCP_URL` and `STITCH_MCP_API_KEY` to communicate with the Stitch platform.
- **Centralized in `.env`**: Store credentials in a root-level `.env` file that the agent runtime loads before execution.
- **Fallbacks exist**: Skills like `upload-to-stitch` accept `--api-url` and `--api-key` CLI flags, but environment variables are the primary configuration method.
- **Optional project ID**: `STITCH_MCP_PROJECT` sets a default project context when the prompt does not specify one.

## Frequently Asked Questions

### What is the Stitch MCP server?

The Stitch MCP (Model-Control-Protocol) server is the bridge that lets Stitch-based skills communicate with the Stitch design platform. It exposes tools that skills invoke to fetch screen definitions, upload designs, and manage projects.

### Where should I place the `.env` file?

Place the `.env` file in the root directory of the agent or project that executes the skills. The repository README and skill documentation assume the runtime loads this file before invoking any MCP tool.

### Can I use command-line flags instead of environment variables?

Yes, but only for specific skills. The `upload-to-stitch` skill documented 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) accepts `--api-url` and `--api-key` flags. However, utility and build skills rely exclusively on environment variables discovered via `list_tools`.

### Why does my skill fail with an authentication error?

Authentication errors indicate that `STITCH_MCP_API_KEY` is missing, contains extra whitespace, or does not match the token in the MCP dashboard. Verify the server is running on the URL specified in `STITCH_MCP_URL` and that no quoting characters surround the values in your `.env` file.