stitch-setup

name	stitch-setup
description	Step-by-step installer for the stitch-kit plugin and Stitch MCP server. Use this when setting up the plugin for the first time, diagnosing connection issues, or helping a new user get Stitch running in Claude Code or Codex CLI.
allowed-tools	["Bash","Read","Write"]

stitch-kit Setup Guide

Walks users through two setup tasks:

1. Stitch MCP Server — connect your AI client to Google Stitch's remote generation API
2. stitch-kit Plugin — install the skills that orchestrate the Stitch workflow

---

When to use this skill

• User says "how do I set this up", "it's not working", "Stitch isn't available"
• Agent can't find Stitch MCP tools after running list_tools
• First-time setup in a new environment

---

Step 1: Verify what's already installed

Run list_tools (or check the tool list). Look for any of:

• create_project
• generate_screen_from_text
• get_screen

If found: Stitch MCP is working. Skip to Step 4 (plugin install). If not found: Continue with MCP setup below.

---

Step 2: Get a Stitch API Key

Stitch MCP is a remote HTTP server — it lives in the cloud at stitch.googleapis.com, not on your machine. It requires an API key to authenticate.

1. Go to stitch.withgoogle.com/settings
2. Scroll to the API Keys section
3. Click "Create API Key"
4. Copy the key — you'll need it in the next step

Never commit your API key to a public repository. Store it securely.

---

Step 3: Configure Stitch MCP

Claude Code

Using the CLI (recommended):

claude mcp add stitch --transport http https://stitch.googleapis.com/mcp \
  --header "X-Goog-Api-Key: YOUR-API-KEY" -s user

Or add to ~/.claude/settings.json manually:

{
  "mcpServers": {
    "stitch": {
      "type": "http",
      "url": "https://stitch.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.stitch]
url = "https://stitch.googleapis.com/mcp"

[mcp_servers.stitch.headers]
X-Goog-Api-Key = "YOUR-API-KEY"

Cursor

Create or edit .cursor/mcp.json:

{
  "mcpServers": {
    "stitch": {
      "url": "https://stitch.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

VS Code

Open Command Palette → "MCP: Add Server" → HTTP → https://stitch.googleapis.com/mcp → name: "stitch". Then edit the generated mcp.json to add the header:

{
  "servers": {
    "stitch": {
      "url": "https://stitch.googleapis.com/mcp",
      "type": "http",
      "headers": {
        "Accept": "application/json",
        "X-Goog-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

Quick install (all platforms)

Or use the NPX installer — it prompts for the API key and configures everything:

npx @booplex/stitch-kit

Manual verification

After adding, restart the client and run list_tools. You should see tools like create_project, generate_screen_from_text, get_screen, etc.

---

Step 4: Install stitch-kit plugin (Claude Code)

/plugin marketplace add https://github.com/gabelul/stitch-kit.git
/plugin install stitch-kit@stitch-kit

All 34 skills in one command. The stitch-kit agent is included — it shows up automatically after restart.

---

Step 5: Verify the full setup

Run the orchestrator to confirm everything works:

"Use Stitch to design a simple login screen"

Expected behavior:

1. stitch-orchestrator activates
2. It runs list_tools and finds Stitch MCP tools
3. It generates a Design Spec
4. It creates a project via create_project
5. It generates a screen via generate_screen_from_text
6. It retrieves the screen via get_screen
7. It asks you which framework to convert to

If this completes, you're fully set up.

---

Troubleshooting

Symptom	Likely cause	Fix
list_tools doesn't show Stitch tools	MCP not configured or client not restarted	Redo Step 3; restart your client
"Unauthenticated" or 401 error	API key invalid or expired	Generate a new key at stitch.withgoogle.com/settings
create_project fails with 403	Account doesn't have Stitch access	Visit stitch.withgoogle.com and request access
generate_screen_from_text returns empty	Bad prompt or project ID format	Use stitch-mcp-generate-screen-from-text skill — it includes ID format rules
get_screen returns 404	Wrong ID format	projectId and screenId must be numeric only — no projects/ prefix
Generated HTML won't download	GCS URL expired or requires redirects	Use bash scripts/fetch-stitch.sh "[url]" "temp/output.html"
Plugin not activating	Wrong install command or repo URL	Verify you used @stitch-kit — not @stitch-pro or @stitch-skills

---

Network requirements

Stitch MCP makes outbound requests to:

• stitch.googleapis.com — remote MCP server
• storage.googleapis.com — file downloads (HTML, screenshots)
• accounts.google.com — OAuth (if using OAuth instead of API key)

If you're behind a corporate proxy or VPN, ensure these domains are allowed.

---

Offline / no-MCP mode

If you cannot configure Stitch MCP, the orchestrator still works in prompt-only mode:

• Steps 1–3 run normally (spec generation, prompt assembly)
• Instead of generating the screen, it outputs a ready-to-copy Stitch prompt
• You paste that prompt at stitch.withgoogle.com manually
• Then you can still use the conversion skills on the downloaded HTML

---

Authentication alternatives

OAuth (for restricted environments)

If you can't store API keys on disk, Stitch supports OAuth via Google Cloud:

gcloud auth login
gcloud auth application-default login
gcloud config set project YOUR-PROJECT-ID
gcloud beta services mcp enable stitch.googleapis.com --project=YOUR-PROJECT-ID

Then use Bearer token auth instead of API key. See full OAuth guide.

Note: OAuth tokens expire hourly and need manual refresh. API keys are simpler for most users.

---

References

• Official Stitch MCP setup: https://stitch.withgoogle.com/docs/mcp/setup
• Plugin repo: https://github.com/gabelul/stitch-kit
• Skills index: docs/skills-index.md
• MCP tool reference: docs/mcp-naming-convention.md