# Archive Connectors Guide **New in v1.0.0-rc.2.** ClioDeck ships three public-archive connectors as MCP tools on its built-in server. The Brainstorm chat can call them through the MCP tool-use loop; external MCP clients (Claude Desktop, Claude Code) can call them too once you've enabled the MCP server. | Connector | Endpoint | API key | Status | |---|---|---|---| | **Gallica (BnF)** | SRU, public | None | Active by default | | **HAL (CCSD)** | Solr, public | None | Active by default | | **Europeana** | REST, requires `wskey` | **Required** — free, from [pro.europeana.eu](https://pro.europeana.eu/pages/get-api) | Inactive until a key is configured | The connectors live in `backend/mcp-server/tools/searchGallica.ts`, `searchHal.ts`, `searchEuropeana.ts`. They are registered unconditionally in `backend/mcp-server/server.ts`; Europeana checks for a key at *call* time and returns a typed `missing_api_key` error if none is set. --- ## Gallica [Gallica](https://gallica.bnf.fr) is the digital library of the Bibliothèque nationale de France. The connector queries Gallica's public SRU endpoint — no key, no quota beyond standard rate limiting. Tool: `search_gallica`. | Input | Type | Required | Notes | |---|---|---|---| | `query` | string | yes | Free-text query. Gallica indexes many languages, but the catalogue's metadata is French-first. | | `topK` | int 1–200 | no (default 10) | Number of hits. | | `dateFrom` | int 0–9999 | no | Earliest publication year (inclusive). | | `dateTo` | int 0–9999 | no | Latest publication year (inclusive). | | `docType` | string | no | Filter on Dublin Core `dc:type` (e.g. `monographie`, `périodique`, `carte`). | --- ## HAL [HAL](https://hal.science) is the French open archive for scientific publications, hosted by CCSD (CNRS). The connector hits HAL's public Solr endpoint. Tool: `search_hal`. | Input | Type | Required | Notes | |---|---|---|---| | `query` | string | yes | Free-text Solr query. HAL indexes many languages. | | `topK` | int 1–200 | no (default 10) | Number of hits. | | `dateFrom` | int 0–9999 | no | Earliest production year (inclusive). | | `dateTo` | int 0–9999 | no | Latest production year (inclusive). | | `docType` | string | no | HAL `docType_s`. Common values: `ART` (journal article), `COMM` (conference paper), `THESE` (thesis), `OUV` (book), `COUV` (book chapter), `REPORT`. | --- ## Europeana [Europeana](https://www.europeana.eu) aggregates content from European museums, libraries and archives — around 50 million items. The connector needs a free API key (`wskey`). Tool: `search_europeana`. | Input | Type | Required | Notes | |---|---|---|---| | `query` | string | yes | Free-text query. | | `topK` | int 1–200 | no (default 10) | Number of hits. | | `mediaType` | enum | no | One of `IMAGE`, `TEXT`, `VIDEO`, `SOUND`, `3D`. | ### Getting and storing your Europeana key 1. Go to [pro.europeana.eu/pages/get-api](https://pro.europeana.eu/pages/get-api) and request a key (free, immediate). 2. In ClioDeck, open **Settings → Archives**. 3. Paste the key into the **Europeana** field and click **Save**. 4. The status badge turns to **configured**. To rotate, paste a new key over the existing one. To revoke, click **Delete**. The key is encrypted via Electron's `safeStorage` (OS keychain on macOS, libsecret on Linux, DPAPI on Windows) — it is **never** written to `.cliodeck/config.json` and never appears in the workspace export. **This key is global, not per-project.** It lives in the app-wide `cliodeck-secrets` store (`secureStorage`, keyed `mcp.europeana.apiKey`) and is mirrored to `process.env.EUROPEANA_API_KEY` at app startup and on every save/delete in Settings — never re-read per project. Checked specifically for the "does state bleed across a project switch" risk that broke other integrations elsewhere in this wiki (issues #33/#34/#39): there's no risk here, precisely because the key was never project-scoped to begin with — it's the same key regardless of which project is open. ### Using Europeana from an external MCP client The Europeana key stored in **Settings → Archives** only reaches the built-in MCP server when ClioDeck spawns it itself. If you've configured Claude Desktop (or another client) to spawn `cliodeck-mcp` directly, you must also set `EUROPEANA_API_KEY` in the client's MCP server configuration. The server reads the env var at every call, so you can rotate without restarting. See the [MCP Integration Guide](./1.12-MCP-Integration-Guide.md#part-c--connect-external-mcp-clients-to-cliodeck) for the snippet shape. --- ## Usage patterns The three connectors are most useful in two situations: - **From Brainstorm**, when an LLM with tool-use is asked an open-ended question and decides on its own to search Gallica or HAL for a primary source it doesn't have in the local corpus. - **From an external MCP client** (Claude Desktop / Claude Code), as a way to ask a frontier model to plan a research trip or pre-screen archive holdings without ClioDeck's UI in the loop. Results land in the chat as a tool-call event followed by a model turn that cites the returned URLs. The connectors do **not** import items into your bibliography or Tropy archive — those flows stay manual (Zotero connector / Tropy import). --- ## What's not (yet) wired The MCP-tool surface is the same in RC2 for all three connectors; the **UI affordances** differ. Only Europeana currently has a dedicated key-management UI in Settings → Archives, because it is the only connector that requires one. The fusion strategy document mentions FranceArchives and Transkribus as future candidates; they are not implemented in RC2. --- ## See also - [MCP Integration Guide](./1.12-MCP-Integration-Guide.md) - [Brainstorm Mode Guide](./1.11-Brainstorm-Mode-Guide.md)