> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.caesar.xyz/2025-11-27/documentation/integration/mcp-server/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.caesar.xyz/_mcp/server.

# Research MCP Server

The Research MCP server is a hosted MCP endpoint that lets MCP-aware clients call Caesar's **API-key authenticated research endpoints** as tools. It is distinct from the **Docs MCP** server, which only answers documentation questions.

> **Info**
>
> Looking for documentation search? See the [MCP Docs Server](/integration/mcp-server).

## Server URL

```
https://api.caesar.xyz/mcp
```

## Authentication

Pass your Caesar API key as a Bearer token in the `Authorization` header.

```
Authorization: Bearer csk-...
```

## Setup

### OpenCode

Add the research MCP server to your OpenCode config under `mcp` (see the [OpenCode MCP docs](https://opencode.ai/docs/mcp-servers/)):

**`opencode.json`**

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "caesar-research": {
      "type": "remote",
      "url": "https://api.caesar.xyz/mcp",
      "headers": {
        "Authorization": "Bearer ${CAESAR_API_KEY}"
      },
      "enabled": true
    }
  }
}
```

Set your API key in the environment:

```bash
export CAESAR_API_KEY=csk-...
```

### Cursor

Add a remote MCP server in `mcp.json` (see [Cursor MCP docs](https://cursor.com/docs/context/mcp)):

**`mcp.json`**

```json title="mcp.json"
{
  "mcpServers": {
    "caesar-research": {
      "url": "https://api.caesar.xyz/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CAESAR_API_KEY}"
      }
    }
  }
}
```

Set your API key in the environment:

```bash
export CAESAR_API_KEY=csk-...
```

### Claude Code

Use the CLI to add the remote HTTP server with your API key (see [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)):

```bash
claude mcp add --transport http caesar-research https://api.caesar.xyz/mcp \
  --header "Authorization: Bearer $CAESAR_API_KEY"
```

Set your API key in the environment before running the command:

```bash
export CAESAR_API_KEY=csk-...
```

### Codex

Add the server in `~/.codex/config.toml` (see [Codex MCP docs](https://developers.openai.com/codex/mcp/)):

**`config.toml`**

```toml title="config.toml"
[mcp_servers.caesar_research]
url = "https://api.caesar.xyz/mcp"
bearer_token_env_var = "CAESAR_API_KEY"
```

Set your API key in the environment:

```bash
export CAESAR_API_KEY=csk-...
```

### Droid

Add the HTTP server with the CLI (see [Droid MCP docs](https://docs.factory.ai/cli/configuration/mcp)):

```bash
droid mcp add caesar-research https://api.caesar.xyz/mcp --type http \
  --header "Authorization: Bearer $CAESAR_API_KEY"
```

Set your API key in the environment before running the command:

```bash
export CAESAR_API_KEY=csk-...
```

## Tools

The MCP server mirrors the existing research endpoints and exposes them as tools.

### Research jobs

| Tool                  | Endpoint                    |
| --------------------- | --------------------------- |
| `research_create`     | `POST /research`            |
| `research_list`       | `GET /research`             |
| `research_get`        | `GET /research/{id}`        |
| `research_brainstorm` | `POST /research/brainstorm` |

### Files & collections

| Tool                          | Endpoint                                        |
| ----------------------------- | ----------------------------------------------- |
| `research_file_upload`        | `POST /research/files`                          |
| `research_files_list`         | `GET /research/files`                           |
| `research_result_content`     | `GET /research/{id}/results/{resultId}/content` |
| `research_collections_create` | `POST /research/collections`                    |
| `research_collections_list`   | `GET /research/collections`                     |
| `research_collections_get`    | `GET /research/collections/{id}`                |
| `research_collections_patch`  | `PATCH /research/collections/{id}`              |

### Chat & updates

| Tool                        | Endpoint                                      |
| --------------------------- | --------------------------------------------- |
| `research_chat_list`        | `GET /research/{id}/chat`                     |
| `research_chat_create`      | `POST /research/{id}/chat`                    |
| `research_chat_message_get` | `GET /research/{id}/chat/{message_id}`        |
| `research_chat_stream`      | `GET /research/{id}/chat/{message_id}/stream` |
| `research_events_stream`    | `GET /research/{id}/events`                   |
| `research_update_create`    | `POST /research/{id}/updates`                 |
| `research_updates_list`     | `GET /research/{id}/updates`                  |

## File uploads

Use `research_file_upload` with base64-encoded content:

```json
{
  "file_name": "report.pdf",
  "content_base64": "...",
  "content_type": "application/pdf",
  "collection_id": "<optional-uuid>"
}
```

## API version override (optional)

Every tool accepts an optional `api_version` argument to set the `API-Version` header when calling the underlying endpoint.

> Expose Caesar research endpoints as MCP tools