> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hemsy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect to the Hemsy visualize MCP server from Cursor, Claude, ChatGPT, or any MCP client.

The Hemsy MCP server exposes a single tool, `visualize`, over stateless Streamable HTTP.

```text theme={null}
Server URL:  https://api.hemsy.ai/mcp
Auth:        Authorization: Bearer hemsy_...

Keyed URL:   https://api.hemsy.ai/mcp/hemsy_...
Auth:        none (key is in the path) — for connector UIs that only offer OAuth or no-auth
```

## Connect a client

Most MCP clients take a server URL plus optional headers. Use your API key from [developers.hemsy.ai](https://developers.hemsy.ai) (see [Authentication](/agents/authentication)).

<Tabs>
  <Tab title="Cursor">
    Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

    ```json theme={null}
    {
      "mcpServers": {
        "hemsy-visualize": {
          "url": "https://api.hemsy.ai/mcp",
          "headers": {
            "Authorization": "Bearer hemsy_..."
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude">
    Claude's remote connector UI only offers **OAuth** or **no authentication** — it cannot send a Bearer header. Use the keyed URL:

    ```text theme={null}
    https://api.hemsy.ai/mcp/hemsy_...
    ```

    Register the connector with **no authentication**. The API key in the path is what authenticates the request.
  </Tab>

  <Tab title="ChatGPT">
    ChatGPT's connector UI only offers **OAuth** or **no authentication** — it cannot send a Bearer header. Use the keyed URL:

    ```text theme={null}
    https://api.hemsy.ai/mcp/hemsy_...
    ```

    Register the connector with **no authentication**. The API key in the path is what authenticates the request.
  </Tab>

  <Tab title="Other clients">
    Any client that supports Streamable HTTP MCP works the same way: point it
    at `https://api.hemsy.ai/mcp` and send the `Authorization: Bearer
            hemsy_...` header on every request. The server is stateless: no session
    setup required.

    If the client UI only supports OAuth or no-auth, use the keyed URL
    (`https://api.hemsy.ai/mcp/hemsy_...`) with no authentication instead.
  </Tab>
</Tabs>

## The `visualize` tool

```ts theme={null}
{
  sceneImage: string,              // https URL or data URL (room, person, space)
  products: [{
    title?: string,
    category?: string,             // e.g. "bedding", "sofa", "tops"
    images?: string[],             // product image URLs. Required unless productUrl resolves
    productUrl?: string,           // PDP URL. Unlocks merchant fidelity when it matches a Hemsy store
    productId?: string,            // Shopify product id (optional)
    variantId?: string,            // Shopify variant id (optional, best asset match)
    color?: string,
    tags?: string[]
  }],
  aspect?: "auto"                  // output matches the scene image
}
```

Response (structured content):

```json theme={null}
{
  "ok": true,
  "image": "data:image/png;base64,...",
  "products": [
    { "index": 0, "fidelity": "merchant", "storeSlug": "acme-home" }
  ],
  "usage": { "credits": 1, "balance": 249 }
}
```

## Usage notes

* **Pass only what the user picked.** A search tool may suggest ten products; call `visualize` with the one or two the user actually wants to see. One product per call is the common case; multiple products are composed into the same scene.
* **`productUrl` is the fidelity signal.** When the product page URL belongs to a Hemsy merchant, that item renders with the merchant's catalog reference assets. The response echoes `storeSlug` so you can reuse it in follow-up calls.
* **Renders take on avg. 10 to 20 seconds.** Configure your client's tool timeout accordingly.
* **1 credit per successful render.** Errors (`401` no key, `402` no credits, `429` rate limited) are returned before any render starts.