> ## 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.

# MCP Server

> Connect the Henry MCP server to your favorite clients.

## Overview

The Henry MCP server (`@henrylabs/mcp`) gives Claude, Cursor, Windsurf, VS
Code, Zed, and other MCP-compatible clients access to the Henry Shopping API.

It is a **Code Mode** server: instead of exposing one tool per API endpoint,
it exposes two tools and lets your agent write TypeScript against the
[`@henrylabs/sdk`](/v1/sdk/server/getting-started/quickstart) client. The
agent looks up what it needs with a docs search tool, then performs the whole
task — search, cart, checkout — in a single code execution. This keeps the
tool surface small while giving agents the full SDK.

## Available Tools

The server exposes exactly two tools:

### `search_docs`

Searches the SDK documentation for methods, parameters, and usage examples.
Agents call this first to discover the right approach before writing code.

### `execute`

Runs TypeScript code against a pre-authenticated `HenrySDK` client. The agent
defines an `async function run(client)`; whatever the function returns or
prints comes back as the tool result. The code runs in an isolated sandbox
with no web or filesystem access (see
[Privacy and code execution](#privacy-and-code-execution) for where the
sandbox runs).

A typical `execute` call written by an agent looks like this:

```typescript theme={null}
async function run(client) {
  const search = await client.products.search({
    query: "Nike Air Max",
    limit: 5,
  });
  return search;
}
```

## Setup Instructions

### General

The Henry MCP server ships as a local stdio process.

* Install Node.js 18+ and ensure `npx` is on your path.
* Set `HENRY_SDK_API_KEY` to a key from the
  [Henry Dashboard](https://app.henrylabs.ai).

```sh theme={null}
export HENRY_SDK_API_KEY="your_api_key"
npx -y @henrylabs/mcp@latest
```

### Claude Code

Add the server from your terminal:

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

Or, to share the server with your team, check a project-scoped `.mcp.json`
into the repo root:

```json theme={null}
{
  "mcpServers": {
    "henry": {
      "command": "npx",
      "args": ["-y", "@henrylabs/mcp@latest"],
      "env": {
        "HENRY_SDK_API_KEY": "your_api_key"
      }
    }
  }
}
```

Run `/mcp` inside a Claude Code session to verify the connection.

### Claude Desktop

1. Open `~/Library/Application Support/Claude/claude_desktop_config.json`
   (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
2. Add or merge the following configuration and restart Claude Desktop:

```json theme={null}
{
  "mcpServers": {
    "henry": {
      "command": "npx",
      "args": ["-y", "@henrylabs/mcp@latest"],
      "env": {
        "HENRY_SDK_API_KEY": "your_api_key"
      }
    }
  }
}
```

<Note>
  Claude's web client only connects to remote MCP servers. Use Claude Desktop
  or Claude Code, or host the server yourself with `--transport http` (see
  [Running as a remote server](#running-as-a-remote-server)).
</Note>

### Cursor

1. Open **Cursor Settings > Tools & MCP > New MCP Server**.
2. Add the following to `mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "henry": {
      "command": "npx",
      "args": ["-y", "@henrylabs/mcp@latest"],
      "env": {
        "HENRY_SDK_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Visual Studio Code

1. Open the Command Palette and run **MCP: Open User Configuration**.
2. Add the server to `mcp.json`:

```json theme={null}
{
  "servers": {
    "henry": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@henrylabs/mcp@latest"],
      "env": {
        "HENRY_SDK_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Windsurf

1. Open settings with `Cmd/Ctrl + ,`.
2. Under **Cascade > MCP Servers**, choose **Add custom server**.
3. Paste the snippet below into `mcp_config.json` and save:

```json theme={null}
{
  "mcpServers": {
    "henry": {
      "command": "npx",
      "args": ["-y", "@henrylabs/mcp@latest"],
      "env": {
        "HENRY_SDK_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Zed

1. Open settings with `Cmd + ,`.
2. Add the configuration to your `settings.json`:

```json theme={null}
{
  "context_servers": {
    "henry": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@henrylabs/mcp@latest"],
      "env": {
        "HENRY_SDK_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Others

Any MCP client that supports stdio servers can run the Henry MCP server with:

* **Command**: `npx`
* **Arguments**: `-y @henrylabs/mcp@latest`
* **Environment**: `HENRY_SDK_API_KEY`

## Configuration

### Environment variables

| Variable             | Required | Description                                                                   |
| -------------------- | -------- | ----------------------------------------------------------------------------- |
| `HENRY_SDK_API_KEY`  | Yes      | Your Henry API key from the [Henry Dashboard](https://app.henrylabs.ai).      |
| `HENRY_SDK_BASE_URL` | No       | Overrides the API base URL the SDK client targets (e.g. to point at sandbox). |
| `HENRY_SDK_LOG`      | No       | SDK log level: `debug`, `info`, `warn`, `error`, or `off`.                    |

<Warning>
  `HENRY_SDK_ENVIRONMENT` is **not** read by the MCP server. To target a
  non-production environment, set `HENRY_SDK_BASE_URL` instead.
</Warning>

### CLI flags

| Flag                         | Values                       | Default             | Description                                                                                        |
| ---------------------------- | ---------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
| `--tools`                    | `code`, `docs`               | both                | Tools to explicitly enable.                                                                        |
| `--no-tools`                 | `code`, `docs`               | —                   | Tools to explicitly disable.                                                                       |
| `--code-execution-mode`      | `stainless-sandbox`, `local` | `stainless-sandbox` | Where `execute` runs code: Stainless-hosted sandboxes or locally on the MCP server machine.        |
| `--code-allow-http-gets`     | boolean                      | off                 | Restrict `execute` to SDK methods that map to HTTP GET operations (read-only).                     |
| `--code-allowed-methods`     | regex list                   | all allowed         | Explicitly allow SDK methods, matched against fully qualified names like `client.products.search`. |
| `--code-blocked-methods`     | regex list                   | —                   | Explicitly block SDK methods.                                                                      |
| `--docs-search-mode`         | `stainless-api`, `local`     | `stainless-api`     | Where `search_docs` searches: the Stainless-hosted search API or a local in-memory index.          |
| `--docs-dir`                 | path                         | —                   | Directory of local markdown/JSON docs to include in local docs search.                             |
| `--custom-instructions-path` | path                         | —                   | Path to custom instructions for the MCP server.                                                    |
| `--transport`                | `stdio`, `http`              | `stdio`             | `stdio` for local servers, `http` for remote servers.                                              |
| `--port`                     | number                       | `3000`              | Port to serve on when using the `http` transport.                                                  |
| `--socket`                   | path                         | —                   | Unix socket to serve on when using the `http` transport.                                           |
| `--log-format`               | `json`, `pretty`             | auto                | Log output format; defaults to `json` unless a TTY is detected.                                    |
| `--debug`                    | boolean                      | off                 | Enable debug logging.                                                                              |

Run `npx -y @henrylabs/mcp@latest --help` for the full list.

Common configurations:

```sh theme={null}
# Read-only: only allow SDK methods that map to HTTP GETs
npx -y @henrylabs/mcp@latest --code-allow-http-gets

# Docs search only, no code execution
npx -y @henrylabs/mcp@latest --tools docs

# Keep code execution and docs search entirely on your machine
npx -y @henrylabs/mcp@latest --code-execution-mode local --docs-search-mode local
```

## Privacy and code execution

By default (`--code-execution-mode=stainless-sandbox`), the TypeScript your
agent writes is executed in isolated sandboxes hosted by
[Stainless](https://www.stainless.com/), the platform the server is built on.
The generated code and your API credentials transit Stainless infrastructure
in this mode. Sandboxes have no web or filesystem access beyond calling the
Henry API.

To keep execution entirely on your own machine, pass
`--code-execution-mode=local`. Likewise, `search_docs` queries go to the
Stainless-hosted search API by default; pass `--docs-search-mode=local` to use
an in-memory index built from embedded SDK data (and any `--docs-dir` files)
instead.

## Running as a remote server

Launching with `--transport http` serves the MCP server over Streamable HTTP.
Use `--port` to pick the port or `--socket` to bind a Unix socket:

```sh theme={null}
npx -y @henrylabs/mcp@latest --transport http --port 3000
```

Clients authenticate with an `x-api-key` header instead of the environment
variable:

```json theme={null}
{
  "mcpServers": {
    "henry": {
      "url": "http://localhost:3000",
      "headers": {
        "x-api-key": "your_api_key"
      }
    }
  }
}
```