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.
A hosted endpoint is available — no installation required.
In claude.ai or Claude Desktop:
Open Settings → Connectors.
Click Add custom connector.
Enter the URL: https://mcp.openarchieven.nl/
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:
Tool Name
Description
search_records
Search genealogical records
show_record
Show a single genealogical record
match_record
Match a person to birth and death records
get_births_years_ago
List births from N years ago
get_births
Find birth records
get_deaths
Find death records
get_marriages
Find marriage records
get_archives
List all archives with statistics
get_record_stats
Record count per archive
get_source_type_stats
Record count per source type
get_event_type_stats
Record count per event type
get_comment_stats
Comment count statistics
get_family_name_stats
Family name frequency
get_first_name_stats
First name frequency
get_profession_stats
Profession frequency
get_breakdown
Cross-tabulation grouped by archive, source type, event type, place or year
get_historical_weather
Historical weather from KNMI
get_census_data
Dutch census data 1795–1899
search_transcriptions
Full-text search across page transcriptions of historical documents
browse_transcriptions
Hierarchically browse transcriptions by source archive, archive number or inventory
show_transcription
Retrieve a single page transcription by id
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).
Tool Name
Description
view_transcription
Open one or more transcribed pages (ids: ["NL-SdmGA_1504889_11", …]) in a deep-zoom IIIF viewer with the transcript; optional highlight_term
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).
Tests cover the per-tool TTL strategy (cache-ttl.ts) using Node's built-in test runner — no extra dependencies. The coverage test asserts every tool emitted by generate.ts has an explicit TTL entry, so re-running npm run generate after an upstream OpenAPI change will surface any new tool that needs a TTL decision.
Server runs normally without Redis. Check REDIS_URL in .env.
Rate limit errors (429)
The upstream API allows 4 req/s per IP. The built-in rate limiter queues requests automatically. If you are running multiple server instances, reduce RATE_LIMIT_RPS or use a shared queue.
Privacy Policy
This server is a thin proxy over the public
Open Archives API. It does not require user
authentication and does not collect personal data of its own.
The full privacy policies of the operators apply in addition to this section:
Tool arguments (e.g. a search name, an archive code, a record
identifier) are received from the MCP client.
HTTP request metadata — method, path, status code, latency, and the
source IP — is observed by the reverse proxy in front of the hosted
endpoint at mcp.openarchieven.nl.
No accounts, cookies, tokens, or session identifiers are collected.
The server is anonymous-by-design.
Use and storage
Tool arguments are forwarded verbatim over HTTPS to
https://api.openarchieven.nl/1.1 to fulfill the request, and the
upstream response is returned to the caller.
Application logs (tool name, arguments, status, latency) are written
to stdout via pino. On the hosted
endpoint these logs are ephemeral: they are not written to disk and
are lost on process restart. Set LOG_LEVEL=warn to suppress argument
logging.
Cache (optional): when Redis is configured, upstream responses are
cached under keys of the form mcp:<tool>:<sorted-params-json>. The
cache contains response bodies only; no user identifiers are stored.
Third-party sharing
No data is sent to any service other than the upstream Open Archives API
listed above. There are no analytics, telemetry, advertising, or
observability third parties involved.
Data retention
Data
Retention
Tool arguments and responses
Not persisted by the application
Application logs
Ephemeral (stdout, lost on restart)
Redis cache entries
Per-tool TTL (6 hours – 7 days; immutable historical lookups never expire). See Redis Cache.
Reverse-proxy access logs
Per the hosting provider's standard retention policy
Security
The MCP endpoint validates the Origin header on every request and
rejects unknown browser origins (DNS-rebinding defense). All transport is
over HTTPS.
External links surfaced to clients
Tool responses include URLs that point to record pages on
https://www.openarchieven.nl. The submission declares the following
allowed link URI so users are not prompted to confirm each link:
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Openarchieven?
Copie nesta página a configuração http para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Openarchieven precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Openarchieven usa?
Openarchieven é acessado por HTTP.
Quando Openarchieven foi verificado pela última vez?
Última verificação: 2026-10-28. MCP server for the Open Archives genealogical search engine.