# Connect your AI assistant

> Add Shortcake as a connector so your assistant can build, preview and request approval for your sites.

Shortcake works through the AI assistant you already use. You add Shortcake once as a connector, sign in, and your assistant can then work on the sites you have access to.

## Quick connection details

| Parameter | Value |
| --- | --- |
| **MCP Server URL** | `https://api.getshortcake.com/v1/mcp` |
| **Transport** | Streamable HTTP (`POST /v1/mcp`) or SSE |
| **Supported MCP Protocols** | `2026-07-28`, `2025-11-25`, `2025-06-18` |
| **Authentication** | OAuth 2.0 (Cognito) |
| **OAuth Client ID** | `4c16673rm8trdku4f809u3gskd` |
| **OAuth Client Secret** | *(leave blank)* |

## Automated setup for AI coding agents & IDEs

If you pointed an AI coding assistant (like Google Antigravity, Claude Code, Cursor, or Hermes Agent) to this page, your assistant can configure everything in one step.

### Quick full setup prompt

Copy and paste this prompt directly into your assistant to install the CLI, configure MCP, and verify your connection:

```text
Set up Shortcake on my system:

1. Prerequisites:
   - Check if Node.js 20 or newer is installed ('node -v'). If missing or older than v20, advise me on installing Node.js 20+.

2. CLI Installation:
   - Install the Shortcake CLI globally (ensure the exact package name '@getshortcake/cli' is used, never plain 'shortcake'):
     npm install -g @getshortcake/cli

3. MCP Server Configuration:
   Configure the Shortcake MCP server for my current AI assistant environment:
   - Server URL: https://api.getshortcake.com/v1/mcp
   - OAuth Client ID: 4c16673rm8trdku4f809u3gskd
   - Client Secret: (leave empty / none)
   Specific setup by agent:
   - Claude Code: run 'claude mcp add --transport http --client-id 4c16673rm8trdku4f809u3gskd shortcake https://api.getshortcake.com/v1/mcp'
   - Google Antigravity: create '~/.gemini/config/plugins/shortcake/plugin.json' and 'mcp_config.json' with the MCP server URL and OAuth client ID.
   - Hermes Agent: run:
     hermes config set mcp_servers.shortcake.url https://api.getshortcake.com/v1/mcp && hermes config set mcp_servers.shortcake.auth oauth && hermes config set mcp_servers.shortcake.oauth.client_id 4c16673rm8trdku4f809u3gskd && hermes config set mcp_servers.shortcake.oauth.redirect_host localhost && hermes config set mcp_servers.shortcake.oauth.redirect_port 47821
   - Cursor / Windsurf / Claude Desktop: add 'shortcake' with URL 'https://api.getshortcake.com/v1/mcp' to the active MCP settings.

4. Sign-in & Authentication:
   - Trigger the login flow with 'npx @getshortcake/cli login' (opens the Shortcake login page in the browser).
   - If using Hermes, run 'hermes mcp login shortcake'. If using Claude Code, use '/mcp' to authenticate if needed.

5. Verification (Read-Only):
   - Check connection status and list accessible projects.
   - IMPORTANT: Only run read-only checks (call 'get_status' and 'list_projects' via MCP, or run 'npx @getshortcake/cli status'). Do not create, edit, publish, or promote anything.
   - Report the status, workspace name, and available website projects back to me.
```

### CLI commands

Run one of the following commands in your terminal or have your agent execute it:

- **Google Antigravity CLI (`agy`)**:
  ```bash
  agy mcp add shortcake https://api.getshortcake.com/v1/mcp
  ```

- **Claude Code CLI**:
  ```bash
  claude mcp add shortcake https://api.getshortcake.com/v1/mcp
  ```

### Configuration file (`mcpServers`)

For **Cursor** (`.cursor/mcp.json`), **Claude Desktop** (`claude_desktop_config.json`), or **VS Code**:

```json
{
  "mcpServers": {
    "shortcake": {
      "url": "https://api.getshortcake.com/v1/mcp"
    }
  }
}
```

If your MCP client requires an explicit transport type, use:

```json
{
  "mcpServers": {
    "shortcake": {
      "transport": "sse",
      "url": "https://api.getshortcake.com/v1/mcp"
    }
  }
}
```

### Agent prompt & verification instructions

When instructing an AI assistant to set up Shortcake, you can copy and paste:

> *"Connect to Shortcake's MCP server at `https://api.getshortcake.com/v1/mcp` with OAuth client ID `4c16673rm8trdku4f809u3gskd` (no secret). Once connected and signed in, call `list_workspaces` to confirm the connection and list my available sites."*

#### What the agent must do after connecting:
1. **Authenticate**: Prompt or guide the user through the one-time Shortcake OAuth sign-in if prompted by the client.
2. **Verify connection**: Call `list_workspaces` to confirm token validity and show available client workspaces.
3. **Follow the Shortcake lifecycle contract**:
   - Locate site files using `get_site_map` and read them with `get_source`.
   - Save file edits with `save_changes` (draft saves do not trigger a build).
   - Generate preview URLs with `create_preview` and inspect them with `get_working_preview`.
   - Never attempt to approve releases on behalf of clients. Call `request_customer_approval` only when explicitly asked by the user; clients approve via emailed verification link.
   - Publish to production using `publish` only after customer approval is granted and the user explicitly requests publication.
   - For local live views, always run `@getshortcake/cli` (`npx @getshortcake/cli`), never `npx shortcake`.

## Web assistant setup (browser)

If you are using a browser-based AI assistant, add a custom connector using the connection details above. Leave **Client secret** blank; the client ID is public connection information and does not grant access without account sign-in.

When prompted, sign in with your Shortcake account and approve the requested access.

If sign-in reports a redirect URL mismatch, [contact support](/docs/get-help/) with the assistant name and the callback URL it provides. That callback must be registered before the connection can finish.

## Step-by-step setup by assistant

### Claude in your browser (claude.ai)

1. Open [claude.ai](https://claude.ai) in your browser and go to **Customize → Connectors** (or **Settings → Connectors**).
2. Choose **Add → Add custom connector**. Name it **Shortcake** and paste `https://api.getshortcake.com/v1/mcp` as the server URL.
3. Under authentication (**Sign in now → Use your own OAuth client**, or **Advanced settings**), enter the public client ID `4c16673rm8trdku4f809u3gskd` and leave **Client secret** blank.
4. Finish adding the connector, click **Connect** if prompted, and sign in with your Shortcake account.
5. Open a new chat, use **+ → Connectors** to enable **Shortcake**, and ask Claude to list your workspaces or sites.

### Gemini in your browser (gemini.google.com)

1. Open [gemini.google.com](https://gemini.google.com) in your browser with an eligible personal Google account and open **Customize → Connectors** (or **Settings → Connected Apps**, sometimes under **Personal Intelligence**).
2. Under **Custom apps**, choose **Create custom app** (or **Add a custom app**). Name it **Shortcake** and paste `https://api.getshortcake.com/v1/mcp` as the server address.
3. Open **Advanced features → Show more** when offered. Enter the public client ID `4c16673rm8trdku4f809u3gskd` and leave **Client secret** blank.
4. Continue with **Next** and follow the Shortcake sign-in prompts using your invited Shortcake email.
5. In a new Gemini chat, type `@` and select **Shortcake**, then ask it to list your workspaces and sites.

### ChatGPT in your browser (chatgpt.com)

1. Open [chatgpt.com](https://chatgpt.com) in your browser and go to **Settings → Connectors** (or **Connected apps → Custom connectors**).
2. Click **Create** or **Add custom connector**.
3. Enter **Shortcake** as the name, paste `https://api.getshortcake.com/v1/mcp` as the MCP server URL, and choose **OAuth** authentication.
4. If asked for OAuth client details, enter the public client ID `4c16673rm8trdku4f809u3gskd` and leave **Client secret** blank.
5. Save the connector, complete the Shortcake sign-in and approval prompt, and select **Shortcake** from the tools menu in your chat.

## Refresh tools after an update

In Claude, open **Customize → Connectors → Yours → Shortcake**, open the **More options** menu, and choose **Refresh tools list**. Then start a new chat. Starting a new chat alone may retain an older tool catalog.

If new tools are missing or an old **Approve** tool still appears, refresh the list before continuing. The current connector lets your assistant request human review; it cannot approve a release itself. Your assistant controls its own tool-permission prompts, so even read-only checks may ask for permission.

## Choosing a workspace

If you work with more than one client, tell your assistant which client you mean, for example *"Show me the sites for Acme Bakery."* Your assistant can list the workspaces you belong to and pick the right one. If it doesn't know which workspace to use, Shortcake asks it to check with you instead of guessing.

## What your assistant can do

Your assistant can only do what your role allows in each workspace. Depending on your access, it can:

- list your workspaces, sites and releases and check their status,
- show pending client reviews, approved releases awaiting publication, and unconfirmed publications,
- explore the pages, components and images in a site,
- create a site or connect an existing one,
- make changes and build a preview,
- request approval from the client, and
- publish a release the client has approved.

Shortcake checks your access on every request. If someone removes your access, the next request is refused, even if your assistant is still connected.

## Try a focused request

Start with: *“Show me the sites in Acme Bakery’s workspace.”* Confirm the site before asking for changes.

Then try: *“Update the opening hours on this site and build a preview for me to review.”* Your assistant can check the build and show the preview when it is ready. A build still in progress is not a completed preview.

Ask *“What is waiting for review or publication?”* to see pending work. Drafts and builds in progress are not included in that list; ask for the site's releases to find them.

After inspecting the preview, explicitly ask your assistant to send the designated person a review request. That person approves through the emailed link and verification code. Publishing is a separate request after approval.

Preview URLs may be publicly accessible unless hosting access controls are enabled. Do not treat a preview link as private just because the approval link requires verification.
