---
name: gaisho-install
description: Install, authorize, verify or explicitly update the gaisho connection and select the daily shopping skill for the current client.
---

# Install gaisho

US online retail product search for AI agents. The service returns facts, never verdicts such as "worth buying"; you judge.

- MCP URL: `https://mcp.gaisho.co/mcp` (Streamable HTTP)
- Connection name: `gaisho`
- Console: https://app.gaisho.co/console
- This file: https://gaisho.co/skill.md

Use this entry for installation, authorization, verification and explicit updates. For shopping through an established connection, use the installed daily shopping skill. Select the client's file below; do not load both daily workflows.

## Install

Authentication is **sign-in (OAuth) first**: the host opens the gaisho sign-in page, the user signs in with Google and clicks Allow, and no key is typed anywhere. Use an API key if OAuth sign-in is unavailable or fails, including header-only hosts and script calls. Sign-in always needs the user's click in a browser; do everything else yourself and ask the user only for that click and for host controls you cannot operate.

### 1. Connect

Identify the current host and its available connection capabilities. Choose a supported route below; the named hosts are examples, not a restriction on which clients can connect. If a connection to gaisho already exists, including one under an older name or URL, rename it to `gaisho` and update it to the URL above instead of adding a second one; preserve other servers.

#### Common hosts where you can add the connection yourself

The table shows common examples. For other hosts and general-purpose agents, including Muse, use the general route below.

| Host | Add | Sign in |
| --- | --- | --- |
| Claude Code | `claude mcp add --scope user --transport http gaisho https://mcp.gaisho.co/mcp` | Ask the user to run `/mcp`, select `gaisho` and authenticate. |
| Codex CLI / Codex app | `codex mcp add gaisho --url https://mcp.gaisho.co/mcp` | Sign-in opens when the server is added; otherwise run `codex mcp login gaisho`. |
| Gemini CLI | `gemini mcp add --transport http gaisho https://mcp.gaisho.co/mcp` | Ask the user to run `/mcp auth gaisho`. |
| Cursor | Add `"gaisho": {"url": "https://mcp.gaisho.co/mcp"}` under `mcpServers` in `~/.cursor/mcp.json` (or the project's `.cursor/mcp.json`). | Ask the user to click the server's login button in Cursor's MCP settings. |
| VS Code / Copilot | Add `"gaisho": {"type": "http", "url": "https://mcp.gaisho.co/mcp"}` under `servers` (not `mcpServers`) in `.vscode/mcp.json` or the user `mcp.json`. | VS Code asks to authenticate when the server starts; ask the user to allow it. |

Merge into an existing JSON file; never overwrite it. Leave every key or header field empty: the server tells the host where to sign in.

#### Other hosts and general-purpose agents, including Muse

Choose by the capabilities available in the current environment, not the client name:

1. Check the host's available tools, settings, CLI help or documentation for remote MCP support and configuration. If supported, add or update `gaisho` with `https://mcp.gaisho.co/mcp`, Streamable HTTP and OAuth. Configure it yourself where possible; give the user only the steps you cannot perform and the sign-in or consent action they must complete.
2. If the host has no native connector but its runtime provides an MCP client with OAuth support, use that client to connect to the same endpoint. Use its supported sign-in and credential storage, and retain the working connection command or client configuration for future calls.
3. If OAuth is unavailable or fails, use the API-key route below. If there is no usable MCP client, install the maintained HTTP script described there. Do not assume an unlisted client, including Muse, requires a script or an API key.

For a script-based agent, record the interpreter, absolute client path, call command and saved tool schemas in the daily skill's `Connection` section. Verify background delivery separately; the ability to call MCP does not establish that results can return automatically.

#### Hosts where only the user can add it

Give the user these exact steps, then wait for them to finish:

- **claude.ai / Claude Desktop / Cowork**: Settings → Connectors → Add custom connector. Name `gaisho`, URL `https://mcp.gaisho.co/mcp`, save, click **Connect**, sign in with Google and click **Allow**.
- **ChatGPT** (web, desktop app): Settings → Apps / Connectors → create a custom connector (some plans first need Developer mode under Advanced settings). URL `https://mcp.gaisho.co/mcp`, authentication **OAuth**, sign in and allow, then enable gaisho in the conversation.
- **Other apps with remote MCP support**: open the app's MCP, tools or connectors settings and add a remote server with the URL above, Streamable HTTP, OAuth.

If the user belongs to an organization, the sign-in page asks whether usage counts toward the person or the organization; let the user choose.

#### No sign-in available: API key

Use this when OAuth sign-in is unavailable or fails, or calls must run from a script or sandbox. Muse also prefers native OAuth when available; script-only Muse setups use this fallback.

1. Ask the user to create a key in the console (API Keys → create; it starts with `gsk_` and is shown once) and to set it as the environment variable `GAISHO_API_KEY` in this environment, or in the host's secret settings. Never ask for the key in the conversation, and never write it into a skill, config file you commit, or a message.
2. If the host takes MCP headers, add the server with the header `Authorization: Bearer ${GAISHO_API_KEY}`, using the host's own syntax for environment variables. Claude Code: `claude mcp add --scope user --transport http gaisho https://mcp.gaisho.co/mcp --header "Authorization: Bearer $GAISHO_API_KEY"`.
3. If the host has no native MCP, install our maintained script by following https://mcp.gaisho.co/references/http.md (Python 3.9+ and curl, no packages; it reads `GAISHO_API_KEY`). Only if it cannot run, use that guide's custom script fallback.

A tool error or empty result is not a reason to switch routes and repeat the call.

### 2. Select and save the daily shopping skill

| Client | Daily skill to install | Supporting files |
| --- | --- | --- |
| Muse | [Muse shopping skill](https://mcp.gaisho.co/muse/shopping.md) | Self-contained; no card reference or `references` folder. |
| ChatGPT | [General shopping skill](https://mcp.gaisho.co/shopping.md) | Save [chatgpt-cards.md](https://mcp.gaisho.co/references/chatgpt-cards.md) as `references/chatgpt-cards.md` inside the skill folder. |
| Other clients | [General shopping skill](https://mcp.gaisho.co/shopping.md) | No card reference required. |

Save the selected daily file as `SKILL.md` in the host's skill location (for example `~/.claude/skills/gaisho/SKILL.md` in Claude Code), or in its persistent instructions if it has no skills. Both daily skills use the frontmatter name `gaisho` for discovery. Keep only the applicable daily workflow enabled. Replace an older daily skill in place, including one installed under an older name, and use `gaisho` as its skill name. Preserve user notes and working connection details; remove only obsolete files belonging to that skill, including `references/shopping-guide.md`.

Do not save this installer as the daily shopping skill or copy its installation steps into that skill. If the previous combined file is installed, replace it with the selected daily file. The installer remains available at https://gaisho.co/skill.md for explicit updates or connection repair.

In the saved copy, replace the text of the `Connection` section with what you verified here:

- Native MCP: the connection name and any tool prefix the host adds (for example `mcp__gaisho__`).
- Script: the interpreter, the absolute script path, the exact `call-tool` command, where the tool schemas are saved, and the client version.
- Background tasks: whether this host can run a task that uses the same gaisho connection, outlives the first reply and delivers its result to the main conversation automatically. Use the host's real tool names; if this is unavailable or unverified, record that so the foreground flow is used.

### 3. Verify

Use a real shopping question if one is pending, otherwise `robot vacuum`:

1. List the tools (native MCP: the host's tool list; script: `client.py list-tools`, saving the schemas). Expect `get_category_overview`, `search_products`, `get_product`, `get_offer`, `vet_price`, `find_deals`, `vet_seller`, `search_products_by_image`, `show_products`.
2. Run the selected daily skill on that question, following its first-reply and research sequence. The general skill grounds the first reply in overview (or the relevant detail/price result for a supplied URL), while independent research runs concurrently when supported; Muse has its own background-search sequence.
3. Verify successful data retrieval and the final response. If background delivery is supported, observe the result return and the final reply; task acceptance alone does not verify automatic delivery. If it fails or is unavailable, record the limitation and use foreground execution.

A saved configuration is not proof; only successful calls are. A 401 means sign-in or the key is missing; finish step 1.

### 4. Report

Tell the user in one short message: the route that works (signed in through native MCP, API key header, or script), where the skill was saved, whether background delivery works, and anything the user still has to do. From now on, shopping questions use only the installed daily skill. For an explicit update, consult this installer again, fetch the selected daily file and preserve its verified `Connection` section. Reuse working authorization; repeat sign-in only when needed.