FOR  ·  AGENTS

For Agents.

The authoritative, machine-facing transport contract for Verity One — stated once, precisely. One source of truth, three surfaces, and the rules a connecting agent must not break.

AUTHORITY INVARIANT
# AUTHORITY
  vo-mcp — a local stdio MCP server, a spawned child process
  proxying to 127.0.0.1:3100, with full READ + WRITE.
  ~25 vo_* tools: memory write / update / retract / forget,
  day-journal, vault, recall, ground.

# NOT AUTHORITY
  The local node serves NO web MCP endpoint.
  POST localhost:3100/mcp -> 404 (by design).

  https://verityone.app/mcp is a MIRROR:
    last-sync reads + queue-only vo.write.intent.
  /hosted-mcp/* is a REST API — NOT an MCP transport.

Authority lives on your machine. Everything off-machine reaches a synced mirror where reads are a snapshot and writes are queued intents — never live authority. See /trust for exactly what the mirror can and cannot do.

THREE SURFACES
01
LOCAL STDIO MCP

Authority. The vo-mcp child process over stdio. Live read and write across all ~25 vo_* tools.

02
verityone.app/mcp

MCP Streamable HTTP — JSON, request/response, NO SSE, sessionless, OAuth-bearer. Mirror-read plus vo.write.intent. VO+ only.

03
/hosted-mcp/*

A hosted REST API (vop_ bearer). REST, not an MCP transport — the name is historical, not the protocol.

LIVE ENTRY POINTS

These all return 200 today. Start at discovery and follow the links — they describe the contract in machine terms.

OAUTH MODEL
AUTHORIZATION SERVER

verityone.app (the hosted service). It issues and validates the web-agent tokens; the protected resource is verityone.app/mcp.

PROTECTED RESOURCE

verityone.app/mcp — the hosted mirror connector, guarded by those tokens.

Two scopes: vo.read (mirror reads) and vo.write.intent (queue a write intent — never a live write). The descriptors above at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource carry the live metadata.

MUST NOT

Seven rules a connecting agent must respect. Breaking any of them produces wrong answers or silent data loss.

  1. 1

    The local node does NOT serve a web/HTTP MCP endpoint. Do not POST to localhost:3100/mcp — it returns 404 by design.

  2. 2

    Hosted reads are NOT live authority. Check the freshness field (mirrored / stale / disconnected); an empty result may simply mean “not synced.”

  3. 3

    source_refs are recorded but NOT fetched or verified. source_link_status only means “a ref was provided.”

  4. 4

    verified_at is auto-stamped at write (it equals created_at) — NOT a re-verification signal.

  5. 5

    Agents CANNOT self-approve memories. POST /memory/approve rejects agent callers; promotion is CLI-only.

  6. 6

    /remember is lossy — it silently drops source_refs and cannot scope to a project. Use POST /memory/write for source_refs, project scope, supersession, and expiry.

  7. 7

    The hosted mirror is server-decrypted — NOT zero-knowledge.

NEXT

One source of truth on your machine. The mirror is a convenience, not an authority — and it never pretends otherwise.

  • /trust — what the hosted mirror is, what it can read, and the encryption model in plain terms.
  • /plus — VO+, the optional web bridge that exposes the verityone.app/mcp connector.