MCP - Hemsy | API Documentation

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

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 (see Authentication).

Cursor
Claude
ChatGPT
Other clients

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "hemsy-visualize": {
      "url": "https://api.hemsy.ai/mcp",
      "headers": {
        "Authorization": "Bearer hemsy_..."
      }
    }
  }
}

Claude’s remote connector UI only offers OAuth or no authentication — it cannot send a Bearer header. Use the keyed URL:

https://api.hemsy.ai/mcp/hemsy_...

ChatGPT’s connector UI only offers OAuth or no authentication — it cannot send a Bearer header. Use the keyed URL:

https://api.hemsy.ai/mcp/hemsy_...

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.

The `visualize` tool

{
  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):

{
  "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.

​Connect a client

​The visualize tool

​Usage notes

Connect a client

The `visualize` tool

Usage notes