citation-mcp

Remote MCP server exposing the CounselStack citation engine as nine legal research tools. This is a thin consumer of citation-api — it owns no data and no extraction logic; it speaks HTTP to the API and packages the proven citator tool layer (schemas, orchestration, honesty guards) in MCP form so any MCP client — Claude first — can drive the engine.

Claude (web/desktop/mobile) ──MCP (Streamable HTTP)──▶  citation-mcp  ──HTTP──▶  citation-api  ──▶  mirror-db

The nine tools

All nine are read-only over immutable reference data and are annotated as such (readOnlyHint), with titles, for connector-directory readiness. Research methodology (tool order, the statutes→mentions front door, treatment honesty rules) ships in the server's instructions field.

Related MCP server: legal-mcp

Run it

npm install
cp .env.example .env        # point CITATION_API_BASE_URL at a running citation-api
npm run dev                 # tsx watch, listens on :3300

# in another terminal:
npm run smoke               # connect, list tools, verify all nine
SMOKE_LIVE=1 npm run smoke  # also exercise citation_lookup against the live API

npm run build && npm start for production (compiles to dist/). The server is stateless (fresh MCP server + transport per request, no sessions), so it deploys as a plain web service and scales horizontally with no sticky routing. GET /healthz for health checks.

Connecting it to Claude

Deploy behind HTTPS, then in Claude: Settings → Connectors → Add custom connector, URL https://<your-host>/mcp. Authless V1 needs no credentials. Requests from allowed browser origins (MCP_ALLOWED_ORIGINS, default claude.ai + claude.com) and server-to-server requests (no Origin header) are accepted; anything else is rejected 403.

Auth: authless now, OAuth-shaped already (Path C)

V1 runs authless (AUTH_MODE=none): no token required, and — by design — no user identity, so no per-user metering. The OAuth 2.1 resource-server shape is already in place so flipping auth on later is additive:

• Every /mcp request crosses authMiddleware (src/auth/auth.ts) — the single boundary. Authless mode threads a null auth context into tool registration.

• AUTH_MODE=oauth activates the RFC 9728 discovery handshake: 401 + WWW-Authenticate: Bearer resource_metadata=... and the /.well-known/oauth-protected-resource document (404 while authless).

• verifyBearerToken is a stub that always rejects — real validation (signature/expiry against the issuer, audience = this server per RFC 8707, subject + scopes extraction) lands when an authorization server exists. Do not enable oauth mode in production until then.

• Outbound, every citation-api call carries CITATION_API_TOKEN as a Bearer when set — a no-op today, this server's API key when the API's key layer ships.

Layout

src/
  index.ts            Express app: origin validation, /healthz, well-known, stateless /mcp
  config.ts           env parsing (AUTH_MODE switch, cache knobs, origins)
  http.ts             HTTP client: result cache, 60s timeouts, __httpError sentinel
  instructions.ts     research methodology → MCP instructions field
  api/client.ts       one function per citation-api endpoint
  orchestration/      the composites: lookup, mentions, read, check, grep, subsection, search
  tools/index.ts      the nine registrations (zod schemas, descriptions, annotations, handlers)
  tools/format.ts     result → model-facing text, incl. the honesty language
  auth/auth.ts        Path C skeleton: middleware, RFC 9728 metadata, stubbed verifier
scripts/smoke.ts      MCP client: list tools, optional live call

Design notes worth knowing:

• Error honesty is a contract. Upstream failures surface as __httpError sentinels and reach the model as "the engine failed — nothing was learned; treat as unverified, not as not-found." A failed scan chunk is counted and the check report says INCOMPLETE. A mentions filter that misses says "not in the top page", never "no case discusses this."

• Result cache (10 min TTL / 500 entries, env-tunable): every endpoint is an idempotent read over immutable law, so identical calls skip the network. Per-instance; correct under horizontal scaling, just less shared.

• CFR mentions works here. The original agent integration had a gap where CFR cites silently returned no mentions; the mapping in orchestration/mentions.ts includes the CFR branch.

Future work (deliberately out of scope for V1)

• CFR topic search tool — the API's /cfr-search exists but has no tool yet (an agent can topic-search statutes, not regulations).

• OAuth authorization server + real token validation + per-user metering.

• Structured (structuredContent) outputs alongside the text blocks.