Install for agents

Every runtime block below expects CAESAR_API_KEY. Sign up in the Caesar app, 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. In a hurry? For agents that support skills, run:

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:

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.

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.

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.

Claude Code

Fastest path for the search skill:

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:

curl -fsSL https://alpha.api.trycaesar.com/skills/install.sh | bash

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

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.

claude mcp add --transport http caesar "https://alpha.api.trycaesar.com/mcp?profile=web-search" \
  --header "Authorization: Bearer $CAESAR_API_KEY"

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

{
  "mcpServers": {
    "caesar": {
      "url": "https://alpha.api.trycaesar.com/mcp?profile=web-search",
      "headers": {
        "Authorization": "Bearer $CAESAR_API_KEY"
      }
    }
  }
}

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

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

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.

Any agent with a skills directory

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

npx skills add caesar-data/skills --skill caesar-search

The installer targets any skills directory via CAESAR_SKILLS_DIR:

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. If your agent uses the skills npm CLI, install from the GitHub shorthand:

npx skills add caesar-data/skills --skill '*' -g -y

Install only the runtime search skill with:

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:

brew install caesar-data/tap/caesar-search

npm install -g caesar-search-cli

curl -fsSL https://raw.githubusercontent.com/caesar-data/caesar-search-cli/main/install.sh | bash

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

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, automation.

Vercel AI SDK

npm install caesar-search ai

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

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:

node -e 'import("caesar-search/ai").then(m => console.log(typeof m.caesarTools))'

Prints function. Details: AI SDK tools.

Raw HTTP

Nothing to install. One authenticated call:

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.

Troubleshooting

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.

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.

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.

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.

​Setup states

​Claude Code

​Cursor, Windsurf, and other MCP clients

​Any agent with a skills directory

​Plain shell agents (CLI)

​Vercel AI SDK

​Raw HTTP

​Troubleshooting

Setup states

Claude Code

Cursor, Windsurf, and other MCP clients

Any agent with a skills directory

Plain shell agents (CLI)

Vercel AI SDK

Raw HTTP

Troubleshooting