How to Configure the Stitch MCP Server with Environment Variables

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, 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 and 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 and 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/.

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

   # .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:

   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 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.

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