ResearchOS: Keeping the evidence attached to the answer

Overview

ResearchOS is a research and writing product for work where a reader needs to inspect how a conclusion was reached. A question becomes a set of objectives; the system discovers available MCP research tools, gathers and evaluates material, and helps the user draft papers from evidence they selected. Claims retain links to evidence records, source excerpts, tool calls, and execution-trace steps.

The writing side supports APA and MLA formats, source limits, exports, and revisions that preserve earlier versions. A research session is a workflow with inspectable state, not a prompt that disappears after one response.

The problem

AI can produce fluent summaries while hiding where a statement came from, what was searched, or what the available sources failed to answer. That makes it hard to verify a claim, cite it responsibly, or revise the work without losing its source trail.

The product needed to let model-assisted research move quickly while keeping source selection, uncertainty, and approval decisions visible to the person using it.

Architecture

1. 01Next.js web appResearch sessions and paper editor
2. 02Node APIPlanning, orchestration, identity, billing
3. 03MCP + model toolsRuntime tool discovery and synthesis
4. 04PostgreSQLWorkspaces, evidence, runs, papers

The Next.js web application is a static Cloudflare Pages frontend. It calls a separate Node API, which owns Firebase Admin verification, PostgreSQL persistence, billing, research orchestration, the Claude API, and MCP connections. Secrets stay on the API host; browser code only receives public configuration.

Engineering decisions

Treat evidence as application data

Claims reference evidence IDs. Evidence records retain the source title, URL, excerpt, retrieval context, MCP server, tool call, and trace step. This gives the interface a concrete path from a sentence back to the material that supports it. Confidence and limitations travel with the evidence rather than being hidden in a prompt transcript.

Put limits and approvals around tools

Tool discovery happens at runtime. Read-only tools can run automatically within bounded iteration, time, and call budgets; tools that can mutate external state require approval. Returned tool content is untrusted input and is validated before it is added to model context.

Keep a server boundary around secrets and durable state

The API is the only layer that receives database, model, Stripe, Firebase Admin, MCP, and tunnel secrets. PostgreSQL stores workspaces, saved research, papers, writing profiles, and short-lived sessions so a workflow can be resumed and reviewed.

Technical challenge and solution

The central challenge is preserving provenance across multiple transformations: a tool result becomes evidence, evidence supports a claim, and claims are assembled into a paper that may later be revised. ResearchOS keeps stable identifiers across those steps and exposes them in the product's trace and evidence views. Paper generation accepts selected research runs and sources, and revisions create a new version rather than overwriting the earlier document.

This design does not make generated writing automatically correct. It gives the user a reviewable source trail and leaves unsupported conclusions visible as gaps instead of treating fluent text as proof.

What I built

I built the research and paper workflows across the Next.js product, Node API, persistence, identity and billing integrations, MCP tool execution, evidence contracts, and deployment setup. The implementation connects user-visible review controls to backend policy and saved workflow state.

Engineering takeaways

• A citation is useful only when the product can preserve the exact evidence it points to.
• Tool output needs the same validation and trust boundaries as other external input.
• Resumable workflows need explicit persisted state, not only a conversation transcript.
• Human review works best when the interface carries evidence and limitations to the decision point.

Stack

Next.js, TypeScript, Node.js, PostgreSQL, Firebase Authentication, Stripe, Anthropic Claude API, Model Context Protocol, Cloudflare Pages, and Docker.