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

# Remote MCP

> Connect any MCP client to Henry's hosted MCP server with one URL.

## Overview

The Henry remote MCP server is hosted by Henry, so there is nothing to install.
Point your MCP client at one URL and sign in with your Henry account:

```
https://mcp.henrylabs.ai/mcp
```

It exposes the Henry Shopping API as one MCP tool per operation — product
search, product details, carts, checkout, orders, and merchants — and ships
interactive product and cart views for clients that support
[MCP Apps](#interactive-views).

<Tip>
  Running an agent with no browser (CI, a server, a scheduled job)? Use the
  [local MCP server](/v1/sdk/server/mcp/mcp) with an API key instead — see
  [Headless agents](#headless-agents).
</Tip>

## Endpoints

| URL                                 | Use it for                                                                                        |
| ----------------------------------- | ------------------------------------------------------------------------------------------------- |
| `https://mcp.henrylabs.ai/mcp`      | Claude, Cursor, VS Code, Windsurf, and other general MCP clients. Every tool, including purchase. |
| `https://mcp.henrylabs.ai/mcp/apps` | ChatGPT apps. Discovery and cart tools only; checkout hands off to Henry's hosted checkout page.  |

Each endpoint issues its own sign-in, and a session for one does not work on
the other.

## Authentication

The server uses OAuth 2.1 with PKCE, discovered automatically by your client.
The first time you connect, your client opens a browser window:

1. Sign in to the [Henry Dashboard](https://app.henrylabs.ai) if you are not
   already signed in.
2. Approve the connection. To use a specific API key instead of your account,
   choose **Use an API key instead** and paste the key.
3. You are sent back to your client, which is now connected.

Your client refreshes the connection automatically. A sign-in currently lasts
**7 days**; after that, your client asks you to sign in again.

<Note>
  Tool calls run as the team whose account or API key you signed in with, and
  count toward that team's usage.
</Note>

## Setup Instructions

### Claude Code

```sh theme={null}
claude mcp add --transport http henry https://mcp.henrylabs.ai/mcp
```

Then run `/mcp` inside a Claude Code session, select **henry**, and choose
**Authenticate**. Add `--scope user` to make the server available in every
project, or `--scope project` to write it to a shared `.mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "henry": {
      "type": "http",
      "url": "https://mcp.henrylabs.ai/mcp"
    }
  }
}
```

### Claude (web and desktop)

1. Open **Settings > Connectors** and choose **Add custom connector**.
2. Name it `Henry` and enter `https://mcp.henrylabs.ai/mcp` as the URL.
3. Choose **Connect** and complete the sign-in.

### ChatGPT

1. Enable developer mode under **Settings > Apps & Connectors > Advanced**.
2. Create a connector with the URL `https://mcp.henrylabs.ai/mcp/apps` and
   OAuth authentication.
3. Complete the sign-in when prompted.

### Cursor

Open **Cursor Settings > Tools & MCP > New MCP Server** and add:

```json theme={null}
{
  "mcpServers": {
    "henry": {
      "url": "https://mcp.henrylabs.ai/mcp"
    }
  }
}
```

### Visual Studio Code

Run **MCP: Open User Configuration** from the Command Palette and add:

```json theme={null}
{
  "servers": {
    "henry": {
      "type": "http",
      "url": "https://mcp.henrylabs.ai/mcp"
    }
  }
}
```

### Windsurf

Under **Cascade > MCP Servers**, choose **Add custom server** and add:

```json theme={null}
{
  "mcpServers": {
    "henry": {
      "serverUrl": "https://mcp.henrylabs.ai/mcp"
    }
  }
}
```

### Others

Any client that supports remote MCP servers over **Streamable HTTP** with
OAuth can connect using the URL `https://mcp.henrylabs.ai/mcp`.

## Available Tools

| Group     | Tools                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------ |
| Products  | `productSearch`, `productSearchStatus`, `productDetails`, `productDetailsStatus`                       |
| Carts     | `cartCreate`, `cartFetch`, `cartList`, `cartAddItem`, `cartUpdateItem`, `cartRemoveItem`, `cartDelete` |
| Checkout  | `cartDetails`, `cartDetailsStatus`, `cartPurchase`, `cartPurchaseStatus`                               |
| Orders    | `ordersList`                                                                                           |
| Merchants | `merchantsList`, `merchantsRetrieve`, `merchantsSearch`                                                |

The `/mcp/apps` endpoint omits `cartPurchase`, `cartPurchaseStatus`,
`merchantsRetrieve`, and `merchantsSearch`.

Every tool declares `readOnlyHint`, `destructiveHint`, and `openWorldHint`
annotations, so clients can auto-approve read-only calls and confirm the rest.

### Async tools

Product search, product details, and checkout details run as background jobs.
The first call returns a `refId` and a `processing` status; the agent then
calls the matching `*Status` tool with that `refId` until the status is
`complete`. See [Polling](/v1/sdk/server/guides/polling) for how the
underlying jobs behave.

| Start            | Poll                   |
| ---------------- | ---------------------- |
| `productSearch`  | `productSearchStatus`  |
| `productDetails` | `productDetailsStatus` |
| `cartDetails`    | `cartDetailsStatus`    |
| `cartPurchase`   | `cartPurchaseStatus`   |

## Interactive views

In clients that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps)
(such as Claude and ChatGPT), product search, product details, and cart tools
render an interactive view alongside the result: a product carousel, a product
detail sheet, and a cart with a link to Henry's hosted checkout. Clients
without MCP Apps support receive the same data as a normal tool result.

## Headless agents

The remote server always needs a person to complete one browser sign-in, and
that sign-in expires after 7 days. For agents that run unattended, use the
[local MCP server](/v1/sdk/server/mcp/mcp) instead. It authenticates with an
API key from an environment variable, so it never needs a browser:

```sh theme={null}
claude mcp add henry -e HENRY_SDK_API_KEY=your_api_key -- npx -y @henrylabs/mcp@latest
```

|                   | Remote MCP                 | Local MCP                                             |
| ----------------- | -------------------------- | ----------------------------------------------------- |
| Install           | None                       | Node.js 18+ and `npx`                                 |
| Auth              | Browser sign-in (OAuth)    | `HENRY_SDK_API_KEY`                                   |
| Unattended / CI   | No                         | Yes                                                   |
| Tool surface      | One tool per API operation | `search_docs` + `execute` (the agent writes SDK code) |
| Interactive views | Yes                        | No                                                    |