Remote MCP server

Caesar serves a remote MCP server at https://alpha.api.trycaesar.com/mcp — the same host as the REST API. It is remote-only today. The server is moving to its own canonical origin, https://mcp.trycaesar.com/mcp, with one-click OAuth connect for hosts like Claude and ChatGPT; the alpha path stays up as a transparent proxy, and raw Bearer keys keep working on both hosts. Until the new origin is live in your environment, use the alpha URL shown in the examples. To make Caesar the agent’s web-search provider, connect the web-search profile. It exposes generic tool names (web_search, web_fetch) that agents naturally choose for web lookup and URL-reading tasks:

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

Use this when

You are in a chat or IDE client that supports remote MCP tools.
You want search and read without installing the CLI locally.
You want the agent to preserve doc_id, search_id, and capture_id across tool calls.

Connection states

State	What you see	Next action
Not connected	No `caesar` server in the client config	Copy the client-specific config below.
Connecting	Config exists, but tools are not listed	Restart or reload MCP servers in the client.
Connected	Tool list includes `web_search` and `web_fetch` on the web-search profile	Run a one-result search and read the best `doc_id`.
Needs authorization	The client shows a “Connect”/login prompt	Approve in the browser — OAuth-capable hosts discover the login flow from the server’s 401 challenge.
Failed	HTTP 401, HTTP 429, or transport error	Use the matching recovery block in Install for agents or rate limits.

Server facts

Fact	Value
Endpoint	`https://alpha.api.trycaesar.com/mcp`
Web-search profile	`https://alpha.api.trycaesar.com/mcp?profile=web-search`
Transport	MCP streamable HTTP, stateless, plain JSON responses (no SSE required)
Server identity	name `caesar`, title `Caesar Search`, version `0.1.0`
Tools	`web_search`, `web_fetch` (feedback is REST/CLI/SDK-only)
Protocol versions	`2025-11-25` (latest), `2025-06-18`, `2025-03-26`, `2024-11-05`
Authorization	Dual-mode: OAuth 2.1 (authorization code + PKCE `S256`, RFC 8707 audience binding) or a raw Bearer API key
Resource metadata	`/.well-known/oauth-protected-resource` (RFC 9728), also at the `/mcp` path-inserted form

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). Legacy tools/call requests for caesar_search and caesar_read are still accepted for existing clients, but those names are not advertised by tools/list.

Connect from other clients

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

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

curl -s https://alpha.api.trycaesar.com/mcp \
  -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/call","params":{"name":"web_search","arguments":{"query":"linux kernel scheduler","max_results":2}}}'

The canonical per-client install matrix lives at Install for agents. Keep the Bearer header in MCP configs and never commit a literal key.

Authentication and rate limits

/mcp sits behind the same auth and rate-limit middleware as the REST endpoints, and supports two credential types:

OAuth (one-click connect). Hosts that implement the MCP authorization spec need no key at all: an unauthenticated request gets HTTP 401 with a WWW-Authenticate challenge pointing at the server’s protected resource metadata, the host discovers the authorization server, and the user approves in the browser (authorization code + PKCE S256). Access tokens are short-lived and audience-bound to the canonical /mcp resource — tokens minted for any other audience are rejected (invalid_token).
Raw Bearer API key. A csk_ or sk_live_ key in the Authorization header skips OAuth entirely — unchanged for CI, Codex-style bearer_token_env_var configs, and every existing integration. A missing credential returns HTTP 401 (missing_api_key), a bad key HTTP 401 (invalid_api_key).

Both resolve to the same organization for billing, usage attribution, and rate limits:

Authenticated connections default to 100 RPS.
Scopes are not enforced on /mcp — any active credential 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.
Your callers’ credentials never reach upstream providers — the server always uses its own provider credentials (no token passthrough).

Tool: web_search

Search the web and get ranked results with snippets, passages, and provenance. Each result carries a doc_id you can pass to web_fetch.

Param	Type	Required	Default	Notes
`query`	string	yes	—	Put constraints (site, filetype, exact phrases, recency) directly in the query text.
`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.
`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 web_fetch (start_char to continue).

Tool: web_fetch

Read a web page as clean markdown with document metadata and provenance. Accepts a url or a doc_id returned by web_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 `web_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.

Scoping the tool set

Append ?tools= to the endpoint URL to limit which tools are advertised and callable — comma-separated, empty means all:

https://alpha.api.trycaesar.com/mcp?tools=web_search

Use ?profile=web-search as a named profile for the same two-tool set:

https://alpha.api.trycaesar.com/mcp?profile=web-search

Tool errors

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, document_not_found, provider_unavailable, internal_error).

For agents

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 web_search result and pass it to web_fetch. 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.

​Use this when

​Connection states

​Server facts

​Connect from other clients

​Authentication and rate limits

​Tool: web_search

​Tool: web_fetch

​Scoping the tool set

​Tool errors

​For agents