Summary

Utopia already stores and exposes a rich epistemic chain internally and through several structured HTTP endpoints:

entity
→ asserted fact
→ evidence / quote
→ source document
→ validity
→ history / correction
→ derived fact
→ proof
→ conflict / review state

However, the documented MCP read surface currently returns much of this information as formatted human-readable text rather than identity-rich structured data.

I would like to clarify what Utopia considers its supported external machine-readable contract for this information.

Tested version

Tested against stock Utopia at:

b03a0f20a3d053323a3ec2669c7c9b4aeb9a8e14

No source, schema, or migration modifications were made.

What I verified

Using the existing HTTP and MCP interfaces, I was able to verify that Utopia has enough underlying information to reconstruct:

• entity identity;
• asserted fact identity and world-time validity;
• evidence quote and chunk identity;
• source document identity and version;
• correction / history events;
• derived fact identity;
• ordered proof premises;
• conflicts / review items.

Most of this information is already available through structured /api/v1/... HTTP routes.

The uncertainty is whether those routes are intended to be stable external integration contracts.

Current MCP limitation

The documented MCP interface is clearly intended for external clients, but tools such as entity_facts primarily return formatted text.

For example, the result can describe validity and identify a derived result with something similar to:

[rule: ...]

but the external caller does not receive a machine-composable structure containing identities such as:

fact_id
evidence_id
document_id
derived_fact_id
proof / premise ids
conflict identity / status

Similarly, change/history output contains useful human-readable information, but does not expose enough stable identities to reliably join it back to the fact/evidence/proof chain.

This makes the MCP surface useful for an interactive agent, but difficult to use as a durable machine-to-machine knowledge interface without parsing formatted prose.

Questions for maintainers

Could you clarify which of the following is the intended direction?

1. Existing structured /api/v1 routes are public external contracts

If so:

• Are integrations expected to depend on the entity, fact, evidence, history, proof, graph, and review routes?
• Is there a compatibility or deprecation policy for those response shapes?
• Are opaque entity/fact/evidence/derived IDs intended to remain usable across versions?

2. MCP is the intended public integration contract

If so, would you consider exposing structured content alongside the human-readable text, including stable opaque identities and lineage relationships?

3. Another external API layer is planned

If neither of the above is intended as the durable contract, is there a planned structured read API for this use case?

Minimal information that seems sufficient

A useful structured external contract would not need to expose database rows or internal implementation details.

Opaque IDs plus typed relationships would be sufficient. For example:

EntityRef {
  id
  name
  type
}

AssertedFact {
  id
  subject
  predicate
  object / value
  valid_from
  valid_to
}

EvidenceRef {
  id
  fact_id
  quote
  chunk_id
  document_id
}

DerivedFact {
  id
  subject
  predicate
  object / value
  rule
}

Proof {
  derived_fact_id
  premises[]
}

HistoryEvent {
  id
  timestamp
  entity_id
  fact_id?
  event_type
}

Conflict {
  id
  fact_ids[]
  kind
  status
}

The exact schema above is only illustrative.

The important properties are:

• stable opaque identity;
• machine-composable lineage;
• asserted and derived facts remain distinguishable;
• evidence and source provenance remain recoverable;
• history/corrections can be joined back to the affected facts;
• conflicts can be addressed as structured objects rather than reconstructed from text.

Why this may be useful beyond one integration

One of Utopia's differentiating properties is that it preserves more than the current graph state.

It also preserves:

• evidence;
• provenance;
• temporal validity;
• changing belief/history;
• derivations and proof chains;
• conflicts;
• auditability.

A structured external read contract would allow downstream agents and applications to preserve those guarantees instead of flattening the result into text and then attempting to reconstruct structure from prose.

It would also provide a clean boundary between Utopia's internal schema—which can continue to evolve—and external integrations that should not depend directly on PostgreSQL tables, migrations, or Rust implementation details.

Related documentation

Current MCP documentation at the tested commit:

Request

The immediate request is primarily clarification:

What external structured read surface, if any, should integrations treat as a supported compatibility boundary?

If MCP is intended to be that boundary, structured identity-rich responses for the epistemic chain above would close the current gap.

If the existing structured HTTP routes are already intended to be that boundary, documenting their compatibility expectations would also resolve the uncertainty.