Open Archives

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.

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

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

A hosted endpoint is available — no installation required.
- OpenSettings → Connectors.
- ClickAdd custom connector.
- Enter the URL:https://mcp.openarchieven.nl/
- Save and approve when prompted.

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

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 onhttps://www.openarchieven.nl.

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 athttp://localhost:3001/(or your own public URL) the same way as the hosted endpoint above.

Every API operation becomes a tool automatically viagenerate.ts.

Note:Thecallback(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 interactiveIIIFdeep-zoom viewer (OpenSeadragon) with the transcription text alongside, using theMCP Appsextension (io.modelcontextprotocol/ui).

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

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

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

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

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

generated/tools.json generated/spec.json

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

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

[ "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_name_stats", "get_first_name_stats", "get_profession_stats", "get_historical_weather", "get_census_data", "search_transcriptions", "browse_transcriptions", "show_transcription" ]

curl -X POST http://localhost:3001/tools/search_records \ -H "Content-Type: application/json" \ -d '{"name":"Coret"}'

curl -X POST http://localhost:3001/tools/show_record \ -H "Content-Type: application/json" \ -d '{"archive":"hua","identifier":"E13B9821-C0B0-4AED-B20B-8DE627ED99BD"}'

curl -N "http://localhost:3001/events/search_records?name=Coret"

event: page data: {...} event: page data: {...} event: done data: {}

Leave SSE open for 15+ seconds — expect periodic keep-alive lines:

curl -N -X POST http://localhost:3001/stream/search_records \ -H "Content-Type: application/json" \ -d '{"name":"Coret"}'

{"query":{...},"response":{"number_found":...,"docs":[...]}} {"query":{...},"response":{"number_found":...,"docs":[...]}}

curl -X POST http://localhost:3001/ \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-03-26", "capabilities": {}, "clientInfo": { "name": "test", "version": "1.0" } } }'

curl -X POST http://localhost:3001/ \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

curl -X POST http://localhost:3001/ \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "search_records", "arguments": { "name": "Coret" } } }'

Restart the MCP server. Expected in/health:

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 bygenerate.tshas an explicit TTL entry, so re-runningnpm run generateafter an upstream OpenAPI change will surface any new tool that needs a TTL decision.

netstat -ano | findstr :3001 taskkill /PID <PID> /F

Server runs normally without Redis. CheckREDIS_URLin.env.

The upstream API allows 4 req/s per IP. The built-in rate limiter queues requests automatically. If you are running multiple server instances, reduceRATE_LIMIT_RPSor use a shared queue.

This server is a thin proxy over the publicOpen Archives API. It does not require user authentication and does not collect personal data of its own.

- Open Archives — Disclaimer & Privacy
- Coret Genealogy — Privacy Policy

- Tool arguments are forwarded verbatim over HTTPS tohttps://api.openarchieven.nl/1.1to fulfill the request, and the upstream response is returned to the caller.
- Application logs(tool name, arguments, status, latency) are written tostdoutviapino. On the hosted endpoint these logs areephemeral: they are not written to disk and are lost on process restart. SetLOG_LEVEL=warnto suppress argument logging.
- Cache(optional): when Redis is configured, upstream responses are cached under keys of the formmcp:<tool>:<sorted-params-json>. The cache contains response bodies only; no user identifiers are stored.

- Email:genealogie@coret.org
- GitHub:open an issue

Search for academic articles using scholarly vendors.