Integration recipes

Three paths pinned to a specific tool, each with a smoke script that runs them.

Why three pinned recipes

A general integration guide ages badly and cannot be checked. These three are pinned to a named tool, and both scripts this page runs are published and digest-pinned, so you can run the same checks we do rather than take the claim on trust. Three is the number on purpose: two or three verified recipes are worth more than a dozen plausible ones.

Recipe 1 — Claude Desktop and Claude Code

Download and pin tavonel-mcp.mjs as the CLI page describes, then register it with an absolute path. Claude Desktop reads %APPDATA%\Claude\claude_desktop_config.json on Windows and ~/Library/Application Support/Claude/claude_desktop_config.json on macOS; restart the app after editing, because the config is read at launch. Claude Code reads .mcp.json at the root of the project you open, which is the scope to use when a repository and a World belong together. Other MCP clients accept the same object under their own path — check the client's own documentation rather than assuming these two.

{
  "mcpServers": {
    "tavonel": {
      "command": "node",
      "args": ["C:/absolute/path/tavonel-mcp.mjs"],
      "env": {
        "TAVONEL_API_KEY": "tvnl_live_...",
        "TAVONEL_BASE_URL": "https://tavonel.com"
      }
    }
  }
}

Note The key lives in the client's env block or its secret facility, never in args — arguments show up in process listings. The server refuses to start if a tool that writes is ever added to it, so an agent holding this config cannot activate a candidate, revoke a connection or spend anything. Give it a key scoped to reads and nothing else.

Recipe 2 — Python over the public sample World

GET /reproducibility/sample-world needs no key and returns a deterministic sample: three objects, two evidence records, one source version, page and region. Its response carries a Content-Digest: sha-256=:…: header over the exact bytes, so the same verification habit the signed package asks for works here first. The published script tavonel-public-sample.py is the recipe: it recomputes that digest, resolves every object's evidence, checks each region against the 0-1000 page frame, and asserts the object marked research_frontier cites no evidence at all. Python 3.12 and the standard library, nothing else — download it, check it against the digest in /developer/channel.json, and read it before you run it.

curl -fsSO https://tavonel.com/developer/tavonel-public-sample.py
python tavonel-public-sample.py --base-url https://tavonel.com
# sample: 3 objects, 2 evidence records, ... bytes
# digest: sha-256=:...:
#   ev-01 -> src_v_01 page 4 bbox [118, 214, 886, 374]
#   ev-02 -> src_v_01 page 4 bbox [118, 214, 886, 374]
# PUBLIC SAMPLE OK

Note The sample is a product fixture and says so in its own disclosure field: it is unsigned, it is not an activated customer World, and it is not a quality measurement. Use it to build against the shape, not to judge extraction.

Recipe 3 — curl, before you have a key

Three unauthenticated reads answer the three questions an evaluator asks first. /api/v1/capabilities is the same list the upload route validates against, so a format absent from it is refused at upload rather than accepted and dropped. /api/openapi is the contract itself — and carries no promote and no rollback path, because neither exists for a key. /api/export/trust publishes the export signing key, or refuses with EXPORT_SIGNER_NOT_CONFIGURED on a deployment that has none.

# Every readable format, with its tier and its stated limitations. No key.
curl -fsS https://tavonel.com/api/v1/capabilities | jq '{schemaVersion, entries: (.entries | length), contentSha256}'

# The pin a caller keeps: drop contentSha256 -- it is the last key -- and re-serialize.
curl -fsS https://tavonel.com/api/v1/capabilities \
  | jq -S 'del(.contentSha256)' --indent 0 | tr -d '\n' | sha256sum

# The contract, and the two paths it deliberately does not have.
curl -fsS https://tavonel.com/api/openapi | jq '[.paths | keys[] | select(test("promote|rollback"))]'
# []

# Who signs an export here, or the refusal that says nobody does.
curl -fsS https://tavonel.com/api/export/trust | jq '{keyId, publicKeySpkiSha256}'

Note The digest line above is a shape, not a one-liner to trust blindly: jq -S reorders keys and the published digest is taken over the manifest's own key order, so the value it prints will not match unless your jq preserves that order. The procedure that does reproduce it is the one on the capabilities route — delete contentSha256, re-serialize with the key order unchanged — and the published smoke script performs exactly that and fails when it disagrees.

Running all three

Download tavonel-recipe-smoke.mjs, check it against its digest, and run all three with node tavonel-recipe-smoke.mjs, or one at a time with mcp, public-sample or curl. It takes --base-url (or TAVONEL_RECIPE_BASE_URL) and defaults to https://tavonel.com. Every request it makes is an unauthenticated GET: no key, no upload, no compile, nothing that spends. It also re-checks every asset in channel.json against its published digest, which is the check the CLI page teaches by hand.

curl -fsSO https://tavonel.com/developer/tavonel-recipe-smoke.mjs
# Check it before you run it, the same way you check everything else in the channel.
curl -fsS https://tavonel.com/developer/channel.json \
  | jq -r '.assets.recipeSmoke.sha256'
sha256sum tavonel-recipe-smoke.mjs

node tavonel-recipe-smoke.mjs --base-url https://tavonel.com
# ok  capabilities — 12 formats, defaultStatus UNSUPPORTED
# ok  contract — 33 operations, no promote or rollback path
# RECIPES OK