Connect any MCP client to Caesar’s hosted streamable-HTTP server for web search and document reading.
Caesar serves a remote MCP server at https://search-api-staging-779189860552.europe-west1.run.app/mcp — the same host as the REST API. It is remote-only today; a local stdio shim is planned. Connect from Claude Code in one line:
claude mcp add --transport http caesar https://search-api-staging-779189860552.europe-west1.run.app/mcp
No key needed. Anonymous access is live. To attach a partner key, add the header:
claude mcp add --transport http caesar https://search-api-staging-779189860552.europe-west1.run.app/mcp \ --header "Authorization: Bearer $CAESAR_API_KEY"
This is the product MCP server: it searches the web. The docs site will also serve its own docs-search MCP for querying these pages — they are different servers with different tools.
The server returns an mcp-session-id header, but because it is stateless, follow-up JSON-RPC requests work without it. If a client requests an unsupported protocol version, the server answers with its latest (2025-11-25).
/mcp sits behind the same auth and rate-limit middleware as the REST endpoints:
Anonymous works on staging (30 requests/second per client IP).
Bearer keys are optional and partner-restricted but always validated when present: a bad key returns HTTP 401 (invalid_api_key) rather than falling back to anonymous. Keyed connections get the api_key tier (default 100 RPS).
Scopes are not enforced on /mcp — any active key works.
Every JSON-RPC message counts as one rate-limited request. Over the limit, the server returns HTTP 429 (rate_limited). Auth and rate-limit failures are HTTP errors, not MCP tool errors.
Search the web and get ranked results with snippets, passages, and provenance. Each result carries a doc_id you can pass to caesar_read.
Param
Type
Required
Default
Notes
query
string
yes
—
Put constraints (site, filetype, exact phrases, recency) directly in the query text.
objective
string
no
—
Broader task objective; helps retrieval and passage selection.
max_results
integer
no
8
1–50. Values above 50 are clamped to 50; zero or negative values fall back to the default 8. Never errored.
mode
string
no
standard
fast, standard, or research. Anything else is a tool error.
response_format
string
no
compact
compact (title, url, snippet, dates), standard (adds passages, max 2 per result), full (adds capture provenance).
The MCP default is compact — note this differs from the REST default of standard. ids_only is not available over MCP; it (and any unknown value) silently falls back to compact. See response shaping for the shared preset table.The result is a single text content block containing JSON: search_id, results[] with rank, title, url, doc_id, snippet, score, published_at, last_crawled_at (plus passages — max 2 — source_url when it differs from url, and top-level ranker_version/score_scope at standard+, and capture_id/capture_time at full), optional warnings, truncated, and hint.Responses are capped at 20,000 characters. On overflow the server sets truncated: true, sheds all passages first, then drops trailing results (never below 1), and adds the hint:
Truncated to fit the response cap. Narrow the query, lower max_results, or read one document with caesar_read (start_char to continue).
Read a web page as clean markdown with document metadata and provenance. Accepts a url or a doc_id returned by caesar_search — providing neither is a tool error (validation_error: provide either url or doc_id).
Param
Type
Required
Default
Notes
url
string
one of url/doc_id
—
URL of the page to read.
doc_id
string
one of url/doc_id
—
Caesar doc_id from a previous caesar_search result.
query
string
no
—
Focuses content selection on the most relevant sections.
max_chars
integer
no
12000
Max 50,000. Values above the max are clamped; zero or negative values fall back to the default 12,000.
start_char
integer
no
0
Resume a truncated read from this character offset.
The result JSON contains doc_id, url, title, published_at, capture_time, start_char (omitted when 0), char_count, truncated, hint, and content (always markdown).When content is truncated, the hint tells you the exact next offset: Content truncated. Continue reading with start_char=12000. Pass that value back as start_char to get the next window. Continuation reads force full-document selection (a query alongside start_char does not excerpt), so offsets stay contiguous across calls.
Tool failures come back as MCP results with isError: true and a single text block formatted as code: message, where the code matches the REST error codes (validation_error, unsupported_mode, document_not_found, provider_unavailable, internal_error).
The compact default exists to protect your context window. Stay on it for find-then-read loops; request standard only when you need quotable passages, full only when you need capture provenance.
Thread handles: take doc_id from a caesar_search result and pass it to caesar_read. Preserve doc_id, search_id, and capture_id values verbatim — they are opaque identifiers, never reconstruct or abbreviate them.
On a truncated read, continue with the start_char value from the hint instead of retrying with a bigger max_chars.
Out-of-range max_results and max_chars are silently coerced over MCP (high values clamped to the max, non-positive values reset to the defaults) — do not expect REST-style 400s.
Each JSON-RPC message spends one rate-limit token, so batch judgment matters: prefer one well-constrained search over several broad ones.
