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

# Install for agents

> Copy-paste Caesar install blocks for every agent environment, each with a verification step.

Every runtime block below expects `CAESAR_API_KEY`. [Sign up in the Caesar app](https://app.trycaesar.com), create an API key, and keep it in your environment, the CLI key store, or your MCP client config. For a limited time, all accounts receive a \$1,000 starting credit grant. Not sure which surface you need? Start with [CLI vs MCP](/agents/cli-vs-mcp).

In a hurry? For agents that support skills, run:

```bash theme={"system"}
npx skills add caesar-data/skills --skill caesar-search
```

That installs the Caesar search skill from the repo. The API-served installer below installs the full skill bundle plus the Claude Code subagent where supported.

## Setup states

| Path   | Use when                          | Install signal                   | Verify signal                                                 |
| ------ | --------------------------------- | -------------------------------- | ------------------------------------------------------------- |
| Skill  | Your agent reads `SKILL.md`       | `caesar-search` skill is present | CLI search returns `search_id`                                |
| MCP    | Your client supports remote tools | `caesar` server is listed        | Web-search profile tools include `web_search` and `web_fetch` |
| CLI    | Your agent has shell access       | `caesar-search` is on `PATH`     | `caesar-search search ... --json` exits 0                     |
| AI SDK | You are building app tools        | `caesar-search/ai` resolves      | `caesarTools` imports as a function                           |
| REST   | You want raw HTTP                 | no install required              | first response includes `search_id`                           |

Paste one of these prompts into your agent and let it do the work:

<CodeGroup>
  ```text Prompt: skill theme={"system"}
  Set up Caesar search here:
  1. Run: npx skills add caesar-data/skills --skill caesar-search
  2. If this environment cannot run the Skills CLI, run:
     curl -fsSL https://alpha.api.trycaesar.com/skills/install.sh | bash
  3. If caesar-search is missing from PATH, install it with
     "npm install -g caesar-search-cli" or "brew install caesar-data/tap/caesar-search".
  4. Verify: caesar-search search "hello world" --max-results 1 --json
     Requires CAESAR_API_KEY or a key stored with caesar-search auth login
     (opens a browser; use --device over SSH).
  5. Report the install path and the verification output.
  ```

  ```text Prompt: full bundle theme={"system"}
  Set up Caesar search here:
  1. Run: curl -fsSL https://alpha.api.trycaesar.com/skills/install.sh | bash
  2. If caesar-search is missing from PATH, install it with
     "npm install -g caesar-search-cli" or "brew install caesar-data/tap/caesar-search".
  3. Verify: caesar-search search "hello world" --max-results 1 --json
     Requires CAESAR_API_KEY or a key stored with caesar-search auth login
     (opens a browser; use --device over SSH).
  4. Report the install path and the verification output.
  ```

  ```text Prompt: MCP server theme={"system"}
  Add the Caesar MCP server to this environment. The endpoint is
  https://alpha.api.trycaesar.com/mcp?profile=web-search
  (streamable HTTP). Send CAESAR_API_KEY as the header
  "Authorization: Bearer <key>".
  Verify by listing tools — you should see web_search and web_fetch. Use those
  generic tools for ordinary web searches and URL reads.
  ```
</CodeGroup>

## Claude Code

Fastest path for the search skill:

```bash theme={"system"}
npx skills add caesar-data/skills --skill caesar-search
```

Install the four skills (`caesar-search`, `caesar-read`, `caesar-setup`, `caesar-best-practices`) and the `caesar-subagent`:

```bash theme={"system"}
curl -fsSL https://alpha.api.trycaesar.com/skills/install.sh | bash
```

Restart the session (or run `/caesar-setup`) to pick them up. Verify:

```bash theme={"system"}
ls ~/.claude/skills | grep caesar
```

Expect four `caesar-*` directories. The skills drive the `caesar-search` CLI; if it is missing from PATH, `/caesar-setup` installs it.

Alternative (or addition): connect the remote MCP server instead.

<CodeGroup>
  ```bash theme={"system"}
  claude mcp add --transport http caesar "https://alpha.api.trycaesar.com/mcp?profile=web-search" \
    --header "Authorization: Bearer $CAESAR_API_KEY"
  ```
</CodeGroup>

Verify: `claude mcp list` shows `caesar` connected. To see its tools (`web_search` and `web_fetch` on the web-search profile), run `/mcp` inside a session.

## Cursor, Windsurf, and other MCP clients

Add the streamable-HTTP server to your client's MCP config (`.cursor/mcp.json`, Windsurf's `mcp_config.json`, or equivalent):

<CodeGroup>
  ```json theme={"system"}
  {
    "mcpServers": {
      "caesar": {
        "url": "https://alpha.api.trycaesar.com/mcp?profile=web-search",
        "headers": {
          "Authorization": "Bearer $CAESAR_API_KEY"
        }
      }
    }
  }
  ```
</CodeGroup>

<Note>
  Most clients do not expand environment variables inside config files — inject the key value when generating the config, and never commit a literal key.
</Note>

Verify from any shell (the endpoint is stateless and answers plain JSON):

```bash theme={"system"}
curl -s "https://alpha.api.trycaesar.com/mcp?profile=web-search" \
  -H "Authorization: Bearer $CAESAR_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

Expect exactly two tools: `web_search` and `web_fetch`. Details: [remote MCP server](/clients/mcp/remote).

## Any agent with a skills directory

If your agent uses the Skills CLI, install the search skill directly:

```bash theme={"system"}
npx skills add caesar-data/skills --skill caesar-search
```

The installer targets any skills directory via `CAESAR_SKILLS_DIR`:

```bash theme={"system"}
curl -fsSL https://alpha.api.trycaesar.com/skills/install.sh | \
  CAESAR_SKILLS_DIR=~/.agents/skills bash
```

Verify: `ls ~/.agents/skills` shows the four `caesar-*` directories. With `CAESAR_SKILLS_DIR` set, the `caesar-subagent` file is skipped — subagent definitions are Claude Code-specific. Other harnesses ignore the `context: fork` frontmatter and run the skills inline; they still work. Details: [skills](/clients/skills).

If your agent uses the `skills` npm CLI, install from the GitHub shorthand:

```bash theme={"system"}
npx skills add caesar-data/skills --skill '*' -g -y
```

Install only the runtime search skill with:

```bash theme={"system"}
npx skills add caesar-data/skills --skill caesar-search -g -y
```

Do not use bare `npx skills add caesar-search`; `skills` expects a source such as `owner/repo`, a GitHub URL, or a local path.

For Claude Code, prefer the curl installer above because it also writes `~/.claude/agents/caesar-subagent.md`. The `npx skills` path installs the `SKILL.md` folders only.

## Plain shell agents (CLI)

Install `caesar-search` through one channel:

<CodeGroup>
  ```bash Homebrew theme={"system"}
  brew install caesar-data/tap/caesar-search
  ```

  ```bash npm theme={"system"}
  npm install -g caesar-search-cli
  ```

  ```bash cURL theme={"system"}
  curl -fsSL https://raw.githubusercontent.com/caesar-data/caesar-search-cli/main/install.sh | bash
  ```
</CodeGroup>

npm needs Node 20+; the curl installer verifies checksums and lands in `~/.local/bin` (override with `CAESAR_INSTALL_DIR`). Verify:

```bash theme={"system"}
caesar-search search "test" --max-results 1 --json
```

Exit code 0 and a JSON object containing `search_id` and one result. Auth: `export CAESAR_API_KEY=...` or `caesar-search auth login` (browser login; `--device` for SSH). Usage and scripting contract: [CLI usage](/clients/cli/usage), [automation](/clients/cli/automation).

## Vercel AI SDK

```bash theme={"system"}
npm install caesar-search ai
```

The `ai` package (version 5 or later) is an optional peer dependency — install it explicitly. Then:

```ts theme={"system"}
import { generateText } from "ai";
import { caesarTools } from "caesar-search/ai";

const { text } = await generateText({
  model,
  tools: caesarTools(),
  prompt: "What changed in Postgres 17 logical replication?",
});
```

`caesarTools()` returns `web_search` and `web_fetch` wired to a default client that reads `CAESAR_API_KEY`. Pass `caesarTools({ client })` to supply a configured `Caesar` instance. Verify the subpath resolves:

```bash theme={"system"}
node -e 'import("caesar-search/ai").then(m => console.log(typeof m.caesarTools))'
```

Prints `function`. Details: [AI SDK tools](/clients/sdks/ai-sdk).

## Raw HTTP

Nothing to install. One authenticated call:

```bash theme={"system"}
curl -s https://alpha.api.trycaesar.com/v1/search \
  -H 'Authorization: Bearer $CAESAR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query":"test","max_results":1,"response":{"verbosity":"compact"}}'
```

A 200 with a `search_id` confirms access. The OpenAPI spec is served unauthenticated at `/openapi/public.json` on the same host. See the [API reference](/api-reference/index).

## Troubleshooting

<AccordionGroup>
  <Accordion title="CLI exit code 3, or HTTP 401">
    Auth failure. Set `CAESAR_API_KEY` or run `caesar-search auth login`. If a key is already set, it is malformed, expired, or revoked. Check state with `caesar-search auth status --json`.
  </Accordion>

  <Accordion title="Unknown flag or unknown command">
    The installed CLI is outdated. Run `caesar-search update` — it detects the install channel (npm, Homebrew, standalone) and upgrades in place — then retry the exact same command. Do not run `npm update -g` or `brew upgrade` by hand.
  </Accordion>

  <Accordion title="HTTP 429 rate_limited">
    Over the per-key second limit. Back off and retry — the `X-RateLimit-Reset` header gives the window reset, at most about a second away. The CLI and SDKs retry 429 automatically with exponential backoff; if you still see 429, lower request volume or request a higher per-key limit. See [rate limits](/rate-limits).
  </Accordion>

  <Accordion title="MCP connection returns 401">
    Check the `Authorization` header: it must be `Bearer` followed by an active key. Auth failures on `/mcp` are HTTP-level, so the client reports a connection error rather than a tool error.
  </Accordion>
</AccordionGroup>