How to Configure the Stitch MCP Server for Stitch Skills

The Stitch MCP server is configured by running the server instance, exposing its URL and API credentials via environment variables, and allowing skills to automatically discover the server's namespace (such as stitch: or mcp_stitch:) through the list_tools protocol.

The google-labs-code/stitch-skills repository provides AI-powered skills that generate pages, fetch screens, and upload design assets to Google Stitch projects via the Model Control Protocol (MCP). Proper Stitch MCP server configuration ensures seamless communication between the skill runtime and Stitch services.

Prerequisites: Running the Stitch MCP Server

Before any skill can interact with Stitch, you must have a running MCP server instance. As noted in README.md at line 82, all skills require an active Stitch MCP server as a mandatory dependency.

Follow the official Stitch MCP Setup Instructions to start the server. The instance must be network-accessible from your skill runtime, whether running locally at http://localhost:8080 or deployed to Cloud Run.

# Verify server is reachable

curl http://localhost:8080/health

Server Registration and Environment Variables

When the Stitch MCP server starts, it registers itself with the agent runtime using credentials read from the environment.

Required Environment Configuration

Set these variables before launching your skill environment:

• MCP_API_KEY – Authentication token for Google Stitch API access
• MCP_PROJECT_ID – Target Google Cloud project identifier
• MCP_URL – Optional explicit endpoint (defaults to http://localhost:8080)

export MCP_API_KEY="your-stitch-api-key"
export MCP_PROJECT_ID="your-gcp-project-id"
export MCP_URL="http://localhost:8080"  # Optional: overrides default

The skill runtime automatically consumes these variables during initialization to establish authenticated connections.

Dynamic Namespace Discovery via list_tools

Skills do not hard-code the MCP namespace prefix. Instead, they implement a discovery protocol using list_tools.

Discovering the Stitch Prefix

As documented in plugins/stitch-utilities/skills/design-md/SKILL.md, skills query available tools and scan for namespaces matching stitch*:* (e.g., stitch: or mcp_stitch:). The first matching prefix becomes the canonical namespace for all subsequent tool invocations.

# Conceptual implementation based on skill patterns

available_tools = await agent.list_tools()
stitch_namespace = None

for tool in available_tools:
    if tool.name.startswith("stitch:") or tool.name.startswith("mcp_stitch:"):
        stitch_namespace = tool.name.split(":")[0] + ":"
        break

if not stitch_namespace:
    raise RuntimeError("Stitch MCP server not found in available tools")

Invoking Tools with the Discovered Prefix

Once identified, skills prepend this namespace to tool names like create_project, get_screen, or batchCreate. The plugins/stitch-utilities/skills/stitch-loop/SKILL.md details this workflow, which proceeds from discovery through project creation to screen metadata retrieval.

# Example invocations using the discovered namespace

project = await agent.call_tool(
    f"{stitch_namespace}create_project",
    {"name": "E-commerce Dashboard"}
)

screen_data = await agent.call_tool(
    f"{stitch_namespace}get_screen",
    {"screen_id": "home-hero"}
)

Validating the Configuration

After starting the server and setting environment variables, validate the setup by executing any Stitch-related skill, such as stitch-utilities/design-md or stitch-build/react-vite-dashboard.

The skill logs will display the discovered prefix and server endpoint. If the list_tools scan fails to find a stitch*:* pattern, the skill exits immediately with a descriptive error indicating that the Stitch MCP server is unavailable.

Overriding Default Endpoints

Some skills support explicit URL overrides to target non-default server instances. As specified in plugins/stitch-design/skills/upload-to-stitch/SKILL.md, you can pass an explicit MCP URL argument to bypass auto-discovery.

# Explicit server override for upload-to-stitch skill

await upload_to_stitch(
    source_file="design.fig",
    mcp_url="https://stitch-mcp-prod.example.com"
)

Use this approach when connecting to regional deployments or shared development servers that do not run on localhost:8080.

Multi-Server Discovery Patterns

For complex pipelines requiring multiple MCP servers, skills can discover multiple namespaces simultaneously. The plugins/stitch-build/skills/remotion/README.md illustrates this pattern, showing how a single skill workflow discovers both stitch: (for design assets) and remotion: (for video rendering) namespaces within the same execution context.

# Discovery pattern for multiple MCP servers

tools = await agent.list_tools()
stitch_ns = next((t for t in tools if t.startswith("stitch:")), None)
remotion_ns = next((t for t in tools if t.startswith("remotion:")), None)

Summary

• Run the Stitch MCP server before executing any skills, ensuring it is reachable from your runtime environment
• Configure environment variables (MCP_API_KEY, MCP_PROJECT_ID) for automatic authentication, with optional MCP_URL for non-default endpoints
• Implement list_tools discovery to dynamically locate the stitch: or mcp_stitch: namespace rather than hard-coding prefixes in skill logic
• Validate connections by checking skill logs for successful prefix discovery and server URL confirmation
• Use explicit overrides via MCP URL arguments when targeting specific server instances outside the default configuration

Frequently Asked Questions

What happens if the Stitch MCP server is not running?

Skills will fail during the initialization phase with an error indicating that no stitch*:* prefix was found via list_tools. According to the repository's README.md (line 82), a running Stitch MCP server is a strict prerequisite for all skills in the google-labs-code/stitch-skills repository.

How do skills determine which namespace prefix to use?

Skills call list_tools and scan the returned tool names for patterns starting with stitch or mcp_stitch, as implemented in plugins/stitch-utilities/skills/stitch-loop/SKILL.md. The first matching prefix (e.g., stitch:) is extracted and used for all subsequent calls to create_project, get_screen, and batchCreate.

Can I connect to a remote Stitch MCP server instead of localhost?

Yes. While the default configuration targets http://localhost:8080, you can specify a remote endpoint by setting the MCP_URL environment variable or passing an explicit MCP URL parameter in skills that support manual overrides, such as the upload-to-stitch skill documented in plugins/stitch-design/skills/upload-to-stitch/SKILL.md.

Where is the Stitch MCP configuration documented in the source code?

Configuration requirements appear in the root README.md (line 82), discovery protocols are detailed in plugins/stitch-utilities/skills/design-md/SKILL.md and plugins/stitch-utilities/skills/stitch-loop/SKILL.md, override options are specified in plugins/stitch-design/skills/upload-to-stitch/SKILL.md, and multi-server patterns are shown in plugins/stitch-build/skills/remotion/README.md.

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