Skip to main content
Every block below works keyless — the anonymous tier is live. Set CAESAR_API_KEY only if you have a partner key for higher throughput. Not sure which surface you need? Start with the agents guide. 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

RailUse whenInstall signalVerify signal
SkillYour agent reads SKILL.mdcaesar-search skill is presentCLI search returns search_id
MCPYour client supports remote toolscaesar server is listedTools include caesar_search and caesar_read
CLIYour agent has shell accesscaesar-search is on PATHcaesar-search search ... --json exits 0
AI SDKYou are building app toolscaesar-search/ai resolvescaesarTools imports as a function
RESTYou want raw HTTPno install requiredfirst 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://search-api-staging-779189860552.europe-west1.run.app/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
   No API key is required (anonymous tier); if CAESAR_API_KEY is set, use it.
5. Report the install channel and the verification output.

​
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://search-api-staging-779189860552.europe-west1.run.app/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://search-api-staging-779189860552.europe-west1.run.app/mcp
Verify: claude mcp list shows caesar connected. To see its two tools (caesar_search and caesar_read), 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://search-api-staging-779189860552.europe-west1.run.app/mcp"
    }
  }
}
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://search-api-staging-779189860552.europe-west1.run.app/mcp \
  -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: caesar_search and caesar_read. 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://search-api-staging-779189860552.europe-west1.run.app/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 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. Optional auth: export CAESAR_API_KEY=... or caesar-search auth login. 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 caesar_search and caesar_read wired to a default client (reads CAESAR_API_KEY; anonymous works without). 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 keyless call: 
curl -s https://search-api-staging-779189860552.europe-west1.run.app/v1/search \
  -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

Auth failure. Set CAESAR_API_KEY or run caesar-search auth login. If a key is already set, it is malformed, expired, or revoked — an invalid key returns 401 and never falls back to anonymous. Unset it to go keyless. Check state with caesar-search auth status --json.
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.
Over the per-second limit (anonymous tier: 30 requests/second per IP). 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 use an API key. See rate limits.
Check the Authorization header: it must be Bearer followed by an active key. A malformed or revoked key gets 401 even though anonymous access works — remove the header entirely to connect keyless. Auth failures on /mcp are HTTP-level, so the client reports a connection error rather than a tool error.