> ## 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.

# Remote MCP server

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

```bash theme={"system"}
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](/agents/install) or [rate limits](/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

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

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

  ```bash cURL (raw JSON-RPC) theme={"system"}
  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}}}'
  ```
</CodeGroup>

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

## Authentication and rate limits

`/mcp` sits behind the same [auth](/authentication) and [rate-limit](/rate-limits) 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](/concepts/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:

```text theme={"system"}
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:

```text theme={"system"}
https://alpha.api.trycaesar.com/mcp?tools=web_search
```

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

```text theme={"system"}
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](/concepts/errors) (`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.