Skip to content
archAIc
Blog

MCP

archAIc exposes its full surface as a Model Context Protocol (MCP) server. AI agents (Claude Code, the Claude desktop and web clients, VS Code, Goose, any spec-compliant MCP client) connect through OAuth 2.1 and call archAIc tools the same way a human curator clicks through the web UI: search a corpus, list libros, get a DLU, read a page, cite a (page, line) mention.

The MCP server is a separate process from the search engine. The gd-mcp binary speaks the MCP protocol and proxies to gd-server over the internal REST surface, so the same data the web UI sees is the data agents see, with no parallel codepath.

The four-verb surface

Section titled “The four-verb surface”

archAIc collapses the agent-facing surface onto four verbs. Every tool maps to one of them.

VerbWhat it doesRepresentative tools
SearchFind pages or DLUs matching a querysearch, search_flat, semantic_search, natural_language_search, word_cloud, query_stats
BrowseWalk the corpus structurelist_collections, list_libros, list_pages, list_dlus, list_words, get_page, get_page_context, get_page_dlus, dlu_children, dlu_ancestors
ExtractGet the structured data behind a page or DLUget_dlu, get_dlu_text, get_form_data, autofill_dlu, autofill_dlu_status, segment_libro, segment_libro_status
CitePin a claim to a (page, line) mentionevery record returned by Extract carries its mentions; ask_documents adds an LLM-grade citation layer

The two onboarding tools — archaic_briefing and archaic_cookbook — load the same context a spec-compliant client would receive in the MCP instructions field on initialize, for clients that don’t surface that field today.

OAuth 2.1

Section titled “OAuth 2.1”

Authentication is OAuth 2.1 with PKCE. The MCP client redirects through archAIc’s authorization server, the user signs in against archAIc’s local users.db (bcrypt), and the client receives a token scoped to the user’s per-resource visibility. Per-resource visibility and quotas apply to MCP exactly as they apply to the web UI. SAML / OIDC sign-in is queued under spec_sso.md and ships together with IIIF Auth API 2.0.

OAuth scope today is the single mcp:tools; per-tool authorisation derives from the underlying engine API key the MCP proxy uses. Per-scope role mapping (read, gt_write, dlu_write, admin) is queued under spec_sso.md.

No anchor, no entry — applied to MCP

Section titled “No anchor, no entry — applied to MCP”

The foundational rule of archAIc applies to every MCP response. Every entity, event, and relationship carries at least one (page, line) mention with a confidence score. The engine drops unanchored extractions both at write time and at read time, so what the agent sees is what the curator has line-level evidence for.

Agents are expected to cite the (page, line) coords, not just a page number. If a claim cannot be backed by a mention in the payload, the agent must say so explicitly rather than infer. This is what makes archAIc’s outputs catalog-trustworthy.

Three-layer entity model

Section titled “Three-layer entity model”

Every entity (person, place, organisation) carries three identity fields:

  • surface_form — the literal ink as transcribed (“Don Emyl. Romai”). Always populated. Use for verbatim quoting.
  • canonical — the normalised form within this DLU (“Emilio Romay”). May be null.
  • entity_id — cross-DLU corpus-wide authority id. Non-null means “same real-world entity as in DLUs N, M, …”. Today mostly null pending automated authority promotion.

Two entity_id: null rows with matching canonical are probably the same entity; archAIc hasn’t formally said so, and agents are expected to hedge accordingly. The same model applies to event participants, relationship subjects / objects, and place / organisation links.

A worked walk-through

Section titled “A worked walk-through”

A natural-language question, end to end:

“Find every probanza in collection rmcr that mentions a Romay, and cite the specific lines.”

list_dlus(collection="rmcr", type="probanza", limit=200)
    → [ { id: 514, title: "Probanza · pp 10–59", page_count: 50 }, ... ]


for each dlu_id:
    get_dlu(id=dlu_id)
        → { persons: [
              { surface_form: "Don Emyl. Romai",
                canonical:    "Emilio Romay",
                entity_id:    null,
                mentions:     [ { page_num: 12, line_idx: 8, confidence: 0.93 }, ... ] },
              ...
          ] }


filter persons by canonical.contains("romay") || surface_form.contains("roma")
emit (collection, libro, dlu_id, title, person.canonical, mentions)

The agent’s final report cites (rmcr / libro 1 / page 12, line 8), not “page 12 of Libro 1”. A consumer (a researcher, a downstream LLM, an automated catalog enricher) can verify the claim by following the IIIF Content State link archAIc embeds next to each mention. The chain stays inspectable from the agent’s prose back to the original line of ink.

Cookbook patterns

Section titled “Cookbook patterns”

The MCP server ships an embedded cookbook with eight worked workflow patterns, reachable two ways:

  • archaic_cookbook() — tool call, returns the cookbook text.
  • docs://archaic/cookbook — MCP resource, fetched via resources/read on spec-compliant clients.

Patterns covered:

  1. “What does this libro contain?” — list_dlus, segment if empty (with user authorization).
  2. Type-filtered search with a person-level constraint, without burning LLM budget on ask_documents.
  3. Roll up all entities across a libro — list_dlus + per-DLU fuse pending the libro-DLU rollup endpoint.
  4. Find which DLUs cover a page range — get_page_dlus per page, dedupe.
  5. Verify a claim’s provenance — walk from relationship to (page, line) mentions.
  6. Natural-language question against a libro — natural_language_search then verify with get_dlu.
  7. Cross-DLU person reconciliation — surface-form, canonical, entity_id three-step.
  8. Authority promotion sniff — when to flag a likely fuse for SME review.

The cookbook is embedded into the binary; updating it requires a gd-mcp rebuild.

Process model

Section titled “Process model”

The MCP server is a separate process from the search engine. Two binaries:

  • gd-server — the search engine. Serves the REST and IIIF surface to the web UI and other API consumers.
  • gd-mcp — the MCP server. Speaks the Model Context Protocol over Streamable HTTP (port 3032 by default; see StreamableHttpService in gd-mcp/src/main.rs). Proxies to gd-server over its internal REST surface.

The split lets archAIc upgrade the MCP wire protocol (which still moves) without touching the engine, and lets operators run the MCP server on a different host (a DMZ, an agent-only network segment) without exposing the engine itself.

Long-lived MCP sessions cache the server’s instructions field for their lifetime; rebuilding gd-mcp and restarting the container means existing connected agents see the old briefing until they reconnect. New initialize calls always see the current text.

Compatibility notes

Section titled “Compatibility notes”
  • The MCP instructions field is injected into the system prompt by Claude Code, VS Code, and Goose. claude.ai’s web client did not surface instructions as of late 2025; the briefing tool and the resource both exist as mitigations. Re-evaluate when claude.ai documents instructions support.
  • archAIc embeds the cookbook into the binary via include_str!. Documentation updates land with a release, not a hot reload.

References

Section titled “References”