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

# Connect an agent (MCP + CLI)

> Give Claude Code, Claude Desktop, Cursor, or any agent one-shot access to Sapient brain-response scans.

Sapient ships a **Model Context Protocol (MCP) server** and a **CLI**, both on npm. Point any agent at your `sk_live_` key and it can scan video or audio and read the per-second brain response itself, with no glue code. Scans run on [`qualia`](/api-reference/models), the default and only available model right now; `mary` is **temporarily unavailable**.

## One-shot install (Claude Code)

A single command wires Sapient into Claude Code:

```bash theme={null}
claude mcp add sapient --env SAPIENT_API_KEY=sk_live_YOUR_KEY_HERE -- npx -y @thesapientcompany/mcp
```

Open a new Claude Code session and ask it to scan a video. Get your `sk_live_` key from **Settings → API** at [thesapientcompany.com](https://www.thesapientcompany.com).

<Warning>
  Paste your **full** key from Settings → API in place of `sk_live_YOUR_KEY_HERE` — never a truncated, display-only `sk_live_…` value. A key with an ellipsis (`…`) can't go in an HTTP `Authorization` header, so every scan fails.
</Warning>

## Already inside a Claude Code session?

If you're chatting in Claude Code right now and don't want to drop to a terminal, paste this prompt and let Claude install it for you:

```text theme={null}
Install the Sapient brain-response MCP for me. Run this command:

  claude mcp add sapient --env SAPIENT_API_KEY=sk_live_YOUR_KEY_HERE -- npx -y @thesapientcompany/mcp

Then confirm the sapient server connected (run `claude mcp list` and check it shows
as connected), and tell me which tools it exposes. If it didn't connect, show me the
error and how to fix it.
```

Swap in your real `sk_live_` key before sending. Claude will run the command, verify the server is connected, and report back, so you never leave the chat.

## One-shot prompt (install and run a scan)

Drop this into Claude Code (or any MCP-capable agent) to install and run your first scan in one go. Fill in your key and a video URL:

```text theme={null}
Install the Sapient brain-response MCP, then scan a video for me.

1. Run this in the terminal:
   claude mcp add sapient --env SAPIENT_API_KEY=sk_live_YOUR_KEY_HERE -- npx -y @thesapientcompany/mcp
2. Using the Sapient run_scan tool with wait:true, scan this video:
   https://www.instagram.com/reel/XXXXXXXXX/
   Ask for all 4 lenses and include reasons.
3. Show me the per-second timeline (attention, memory, and buy intent at each
   second), plus the moments and the summary. Tell me where attention peaks
   and where it drops.
```

## CLI

Prefer a terminal? The CLI runs a scan and waits for the result:

```bash theme={null}
SAPIENT_API_KEY=sk_live_YOUR_KEY_HERE npx @thesapientcompany/cli scan "https://yourcdn.com/ad.mp4" --wait --reasons
```

Scans run on `qualia` by default — you don't need to pass `--model`. (`--model mary` is temporarily unavailable.) Other commands: `sapient get <scan_id>`, `sapient history`, `sapient intelligence -q "attention"`, `sapient lenses`.

## Install in other tools

Sapient is a standard stdio MCP server, so it drops into any MCP-capable editor or agent. Each one is a single copy-paste. Pick yours:

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

    ```json theme={null}
    {
      "mcpServers": {
        "sapient": {
          "command": "npx",
          "args": ["-y", "@thesapientcompany/mcp"],
          "env": { "SAPIENT_API_KEY": "sk_live_YOUR_KEY_HERE" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`, then refresh MCP servers:

    ```json theme={null}
    {
      "mcpServers": {
        "sapient": {
          "command": "npx",
          "args": ["-y", "@thesapientcompany/mcp"],
          "env": { "SAPIENT_API_KEY": "sk_live_YOUR_KEY_HERE" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex CLI">
    Add to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.sapient]
    command = "npx"
    args = ["-y", "@thesapientcompany/mcp"]
    env = { SAPIENT_API_KEY = "sk_live_YOUR_KEY_HERE" }
    ```

    Or do it in one command:

    ```bash theme={null}
    codex mcp add sapient --env SAPIENT_API_KEY=sk_live_YOUR_KEY_HERE -- npx -y @thesapientcompany/mcp
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json` (Copilot, Cline, and Continue read MCP from here):

    ```json theme={null}
    {
      "servers": {
        "sapient": {
          "command": "npx",
          "args": ["-y", "@thesapientcompany/mcp"],
          "env": { "SAPIENT_API_KEY": "sk_live_YOUR_KEY_HERE" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to your `claude_desktop_config.json` (Settings → Developer → Edit Config):

    ```json theme={null}
    {
      "mcpServers": {
        "sapient": {
          "command": "npx",
          "args": ["-y", "@thesapientcompany/mcp"],
          "env": { "SAPIENT_API_KEY": "sk_live_YOUR_KEY_HERE" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Zed">
    Add to your Zed `settings.json`:

    ```json theme={null}
    {
      "context_servers": {
        "sapient": {
          "command": { "path": "npx", "args": ["-y", "@thesapientcompany/mcp"] },
          "settings": { "SAPIENT_API_KEY": "sk_live_YOUR_KEY_HERE" }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Generic MCP JSON">
    Any client that reads the standard MCP JSON format takes this:

    ```json theme={null}
    {
      "mcpServers": {
        "sapient": {
          "command": "npx",
          "args": ["-y", "@thesapientcompany/mcp"],
          "env": { "SAPIENT_API_KEY": "sk_live_YOUR_KEY_HERE" }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  Every tool runs the same command: `npx -y @thesapientcompany/mcp` with `SAPIENT_API_KEY` set. If your tool isn't listed, use that command in its MCP config and it will work.
</Note>

## What the agent gets

| Tool              | What it does                                                                                                                                                                                                                                   |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_scan`        | Submit content (a video or audio `url`), choose `lenses` and `options`. Scans run on `qualia` (the default and only available model; `mary` is temporarily unavailable). With `wait: true` it polls to completion and returns the full result. |
| `get_scan`        | Fetch one scan by `scan_id`: status while running, the full per-second result when complete.                                                                                                                                                   |
| `list_lenses`     | The 4 selectable lenses with one-line descriptions.                                                                                                                                                                                            |
| `my_history`      | The caller's scan history.                                                                                                                                                                                                                     |
| `my_intelligence` | Cross-scan patterns and semantic recall over everything you've scanned.                                                                                                                                                                        |

It also exposes a resource, `sapient://knowledge-base`, with the full explanation of how the models work, the 7 networks, and how to read a scan, so the agent can ground its own interpretation.

<Note>
  The MCP server is a local **stdio** server: it runs on your machine and talks to the hosted Sapient API. Set `SAPIENT_BASE_URL` to point at a different API host.
</Note>