MCP server

Envelope

ok / err payload shape, _meta fields, and soft-failure semantics shared across every tool.

Envelope

Every DTPR MCP tool returns the same { ok, data | errors, meta } envelope, embedded in the MCP tool-result shape. REST consumers see the identical body shape without the MCP wrapper.

Success envelope

{
  "ok": true,
  "data": { "...": "..." },
  "meta": {
    "content_hash": "sha256-…",
    "version": "ai@2026-04-16-beta",
    "next_cursor": null
  }
}

Field	Meaning
`ok`	`true` for success.
`data`	Tool-specific payload (see each tool page).
`meta.content_hash`	Hex content hash of the schema version being read. Stable across reads of the same version.
`meta.version`	Canonical schema version, e.g. `ai@2026-04-16-beta`.
`meta.next_cursor`	Opaque pagination cursor for `list_elements` / `list_categories`. `null` on the final page.
`meta.warnings`	Optional array of short strings. Emitted by `validate_datachain` / `render_datachain` when a non-blocking issue was found.

Error envelope

{
  "ok": false,
  "errors": [
    {
      "code": "element_not_found",
      "message": "Element 'missing_element' not found in ai@2026-04-16-beta.",
      "path": "elements[0].element_id",
      "fix_hint": "Use list_elements to enumerate available elements."
    }
  ],
  "meta": { "version": "ai@2026-04-16-beta" }
}

Field	Meaning
`errors[].code`	Stable machine-readable code. See Errors.
`errors[].message`	Human-readable diagnostic.
`errors[].path`	Optional JSON path pointing into the caller's payload.
`errors[].fix_hint`	Optional short instruction for a human or agent.

MCP wrapping

Tools return the envelope twice — as typed structuredContent for 2025-06-18-capable clients, and as a JSON string inside content[0].text for older clients:

{
  "structuredContent": { "ok": true, "data": { "...": "..." }, "meta": { "...": "..." } },
  "content": [
    { "type": "text", "text": "{\"ok\":true,\"data\":{...},\"meta\":{...}}" }
  ]
}

Both carry the same payload; read whichever your client supports.

`isError` and soft-failure

Hard failures (transport, arguments, unknown version, internal error) surface with isError: true in the tool result. The MCP client should treat them like exceptions.

Soft failures — where the call ran successfully but the answer is "no" or "invalid" — set ok: false without setting isError. The client should read the envelope and display the semantic result.

The soft-failure pattern is used by three tools:

Tool	Soft-failure case
`validate_datachain`	Instance is well-formed but semantically invalid (missing required categories, wrong element placement, etc.).
`render_datachain`	Same semantic validation as above; rendering aborts rather than returning a broken document.
`get_elements`	One or more requested element ids were not found. The response includes successful hits plus `null` entries for misses.

Soft-failure example (`validate_datachain`)

{
  "structuredContent": {
    "ok": false,
    "errors": [
      {
        "code": "element_required",
        "message": "Category 'purpose' requires at least one element.",
        "path": "elements",
        "fix_hint": "Add an element with category_id='purpose'."
      }
    ],
    "meta": {
      "content_hash": "sha256-…",
      "version": "ai@2026-04-16-beta",
      "warnings": []
    }
  },
  "content": [{ "type": "text", "text": "..." }]
}

Note the absence of isError. The client learned the datachain is invalid; the call itself succeeded.

Envelope

Envelope

Success envelope

Error envelope

MCP wrapping

isError and soft-failure

Soft-failure example (validate_datachain)

See also

`isError` and soft-failure

Soft-failure example (`validate_datachain`)