Open Archives

Open Archives MCP Server

Production-grade hybrid MCP + HTTP + SSE server generated from the Open Archives OpenAPI specification. Covers genealogical records (births, deaths, marriages, censuses), archive statistics, historical weather, and full-text page transcriptions of historical documents.

OpenAPI source used to generate tools:

../api/openapi.yaml   (local)

https://api.openarchieven.nl/openapi.yaml (remote)

---

Overview

A schema-aware server that automatically converts the OpenAPI specification into callable tools and exposes them through multiple transports:

• MCP Remote (JSON-RPC over StreamableHTTP)
• HTTP JSON API
• SSE streaming with auto-pagination
• Chunked HTTP streaming with auto-pagination
• Redis caching (optional)
• Health checks

Video (Dutch): Help AI met jouw erfgoedservices (via MCP)

---

Use with Claude

Add as a custom connector

A hosted endpoint is available — no installation required.

In claude.ai or Claude Desktop:

1. Open Settings → Connectors.
2. Click Add custom connector.
3. Enter the URL: https://mcp.openarchieven.nl/
4. Save and approve when prompted.

No authentication is required — Open Archives is a public dataset.

Example queries

Once the connector is added you can ask Claude, for example:

• *"Who are the ancestors of Johannes Gregorius Marinus Coret? Give me an overview, including source citations in markdown format with the links to the original archives if possible, otherwise provide the Open Archieven links and provide a tree in SVG."*
• *"Did Johannes Coret and Antonia Uphus have descendants? Give me an overview, including source citations in markdown format with the links to the original archives if possible, otherwise provide the Open Archieven links, include thumbnails from scans from archival sources if available and provide a tree in SVG."*
• *"Provide me with a list of sourcetypes per archive(name) where I can find information about the Coret family. Show the result in a markdown document including links to the search pages on Open Archieven. Instead of the archive code use the ISIL if available."*
• *"What was the weather in Amsterdam on 1953-02-01?"*
• *"What does the 1850 census say about Utrecht?"*

Claude will call the matching tool (search_records, show_record, get_marriages, get_historical_weather, get_census_data, …) and return links to the corresponding record pages on https://www.openarchieven.nl.

Self-hosted

The server speaks MCP over Streamable HTTP; there is no stdio distribution. To run your own instance:

git clone https://github.com/coret/openarchieven-mcp-server.git

cd openarchieven-mcp-server npm install npm run generate # builds generated/tools.json from openapi.yaml npm run build:viewer # builds dist/viewer.html (the MCP App) npm start # listens on http://localhost:3001/

Point your MCP client at http://localhost:3001/ (or your own public URL) the same way as the hosted endpoint above.

---

Core Features

OpenAPI Auto-Generation

Every API operation becomes a tool automatically via generate.ts.

All 21 operations:

Note: The callback (JSONP) parameter present in the upstream API is excluded from all tools — it is irrelevant in an MCP/JSON-RPC context.

---

Interactive Transcription Viewer (MCP App)

Beyond the 21 auto-generated tools, the server registers one hand-written tool — `view_transcription` — that opens transcribed pages in an interactive IIIF deep-zoom viewer (OpenSeadragon) with the transcription text alongside, using the MCP Apps extension (io.modelcontextprotocol/ui).

• Apps-capable hosts (Claude web/desktop, paid custom connectors) render the viewer (ui://openarchieven/viewer.html) in a sandboxed iframe that loads images directly from the transcription image hosts (CSP-allowlisted as *.transkribus.eu, *.archief.nl, *.archieven.nl, *.memorix.nl). Transkribus and the archief.nl iipsrv server provide true IIIF deep zoom; the preserve*.archieven.nl thumbnail hosts render as flat images.
• Plain hosts receive a graceful fallback: a text summary with the IIIF/source URLs plus a few inline preview images.

The viewer is a single self-contained dist/viewer.html, bundled at build time with npm run build:viewer (vite + vite-plugin-singlefile); it is not listed by the REST GET /tools endpoint, only via MCP tools/list.

---

Schema-Perfect Validation

Uses actual OpenAPI parameter schemas. Validates:

• required parameters
• integer fields
• number fields
• enum values
• minimum / maximum constraints

---

Multiple Interfaces

MCP Remote (StreamableHTTP)

POST /       ← canonical public endpoint (mcp.openarchieven.nl)

POST /mcp ← local / legacy alias

Stateless JSON-RPC transport — a new MCP server instance is created per request.

Origin validation: Browser requests must come from claude.ai,

claude.com, or any domain listed in ALLOWED_ORIGINS. Requests with no

Origin header (native MCP clients, curl, server-to-server) are

accepted. Unknown origins receive HTTP 403.

HTTP JSON

GET  /tools

POST /tools/:name

SSE Streaming (auto-paginating)

GET /events/:name

Chunked HTTP Streaming (auto-paginating)

POST /stream/:name

Discovery Metadata (/.well-known)

Static, hand-editable JSON files served verbatim from well-known/:

GET /.well-known/mcp/server-card.json   ← SEP-1649 MCP Server Card

GET /.well-known/mcp.json ← alias of the server card GET /.well-known/agent-card.json ← A2A v0.3 Agent Card GET /.well-known/agent.json ← alias of the agent card

Edit well-known/mcp-server-card.json and well-known/agent-card.json directly — no restart required (files are read on each request). Responses are sent with Content-Type: application/json; charset=utf-8 and Cache-Control: public, max-age=3600.

---

Pagination

Streaming endpoints (/events/:name, /stream/:name) automatically paginate through results for endpoints that support a start offset:

• Increments start by number_show per page
• Stops when results are exhausted or after 20 pages (safety cap)
• SSE sends a : heartbeat comment every 10 seconds to keep connections alive

---

Redis Cache

Optional Redis support.

If Redis is running, upstream responses are cached with a per-tool TTL tuned to the data's volatility:

CACHE_TTL (default 3600) is the fallback for any tool not in the map above.

If Redis is unavailable:

• server still runs normally (degraded mode)

---

Rate Limiting

The upstream API enforces 4 requests per second per IP. The server queues all upstream calls through a token-bucket rate limiter (configurable via RATE_LIMIT_RPS).

---

Health Checks

GET /health

---

Project Files

generate.ts

server.ts tsconfig.json package.json .env.example generated/ tools.json spec.json

---

Requirements

• Node.js 18+
• npm
• optional Redis server

---

Configuration

Copy .env.example to .env and adjust:

cp .env.example .env

---

Install

npm install

---

Generate Tools from OpenAPI YAML

Run from local spec:

npx tsx generate.ts

Or from remote URL:

npx tsx generate.ts https://api.openarchieven.nl/openapi.yaml

Expected result:

Generated 21 tools

Output: generated/tools.json, generated/spec.json

Creates:

generated/tools.json

generated/spec.json

---

Start Server

npx tsx server.ts

Expected startup (development — pretty-printed):

[12:00:00] INFO: Open Archieven MCP server started

port: 3001 tools: 21 upstream: "https://api.openarchieven.nl/1.1" rateLimit: "4 req/s" redis: "redis://localhost:6379/5" env: "development"

In production (NODE_ENV=production) each log line is a single JSON object.

Server binds to:

http://0.0.0.0:3001

---

Test All Features

---

1. Health Check

curl http://localhost:3001/health

Expected:

{

"ok": true, "tools": 21, "redis": false, "uptime": 1.23 }

---

2. List Tools

curl http://localhost:3001/tools

Expected:

[

"search_records", "show_record", "match_record", "get_births_years_ago", "get_births", "get_deaths", "get_marriages", "get_archives", "get_record_stats", "get_source_type_stats", "get_event_type_stats", "get_comment_stats", "get_family_n