MCP tools and safety

Use the four canonical management operations with exact scope, Candidate, policy, and recovery evidence.

Jetrepo exposes four Management MCP tools. There is no flat domain mutation catalog or alternate management query endpoint. Models, Content, Assets, Taxonomy, Releases, Environments, integrations, and lifecycle all use versioned Operation Definitions behind the same Candidate and Operation runtime.

Tool listing is a usability filter, not execution authority. Every call resolves the live principal, stable Backend, logical Environment, roles, resource and field scopes, credential state, and authorization version again.

Tool schemas describe each input’s purpose and scope rules. Operation Definition inspection includes both inputSchema and outputSchema; use the input schema for arguments and the output schema to understand the resulting domain value. propose writes a Candidate and is not advertised as idempotent. execute is idempotent for the same execution intent and key; this does not bypass policy or make its domain changes read-only.

Tool permissions

Tool	Permission expression
`inspect`	Kind-specific read permission; returned Operation Definitions are additionally filtered by their requester permissions.
`propose`	`operation.execute` plus every proposed Operation Definition’s requester permission.
`execute`	`operation.execute` plus every exact Candidate operation’s requester permission.
`control_operation`	Action-specific `operation.read`, `operation.approve`, `operation.cancel`, `operation.retry`, or `operation.rollback`; `CLAIM_SECRET` is additionally bound to the exact requesting principal and credential.

inspect supports bounded, permission-filtered discovery for Organizations, Backends, Environments, Preview targets, Vocabularies, Operation Definitions, Candidates, Operations, Delivery, Audit, and Settings. Start with ORGANIZATIONS, which needs no resource scope and returns only live memberships plus exact Backend-creation and Operation-read capability evidence. BACKENDS also needs no Backend or Environment and may be narrowed with an Organization ID. ENVIRONMENTS needs a stable Backend. Organization bootstrap definitions, Candidates, and Operations use an Organization ID without fake Backend or Environment values; normal inspection uses both a stable Backend and exact Environment. Singular CANDIDATE and OPERATION reads also need the resource ID. A page contains at most 100 items and returns an opaque cursor when another page exists. For singular OPERATION inspection, limit bounds item outcomes and cursor continues those outcomes; aggregate succeeded/failed/partial totals remain for the complete Operation.

A scoped credential cannot escape its pinned Backend or Environment by changing arguments. A delegated human sees only resources allowed by current Organization roles. Organization-owned workload keys remain independently narrowed by their fixed permission allowlist and explicit scopes.

Candidate sequence

For an empty Organization, call inspect with kind: "ORGANIZATIONS", select a scope where canCreateBackend is true, then inspect Organization-scoped Operation Definitions. The delegated agent proposes an Organization Change Set whose only operation is backend.create@1. This autonomous bootstrap needs operation.execute and backend.create, creates no fake Backend or Environment scope, and returns the stable Backend, main Environment, and initial Draft manifest in the completed Operation. Organization-scoped Candidate and Operation inspection, resources, notifications, and control_operation status remain available throughout. The agent then uses the returned Backend and Environment for normal Change Sets.

Call inspect with kind: "OPERATION_DEFINITIONS" and either the selected Organization for bootstrap or a stable Backend plus Environment for normal work. Select exact definition names and versions whose schemas match the desired change.
Read the current Draft Projection Manifest and hash with scoped SETTINGS inspection (backend.read). Build a version-1 Change Set over that exact base. Creating operations use a localRef; dependent operations refer to it with a local selector or { "$localRef": "…" }.
Call propose. Jetrepo normalizes arguments and dependencies, validates schemas and domain rules, computes resource and field diffs, delivery/lifecycle/deletion impact, quotas, policy inputs, and a deterministic digest. It persists an immutable Candidate but performs no authoritative domain mutation.
Review the Candidate ID, digest, expiry, validation, diff, requester, and policy. To hand the rendered Candidate to a reviewer, run the agent-native Preview handoff sequence below; Preview, policy Approval when required, and execution all bind this same digest.
Call execute with the same Backend and Environment, exact Candidate ID/digest, and a caller-chosen idempotency key. Organization bootstrap omits Backend and Environment. Jetrepo creates or resumes one durable Operation. Reusing the key for another Candidate is a conflict.
Read the Operation resource or use control_operation with STATUS. Autonomous work enters QUEUED; policy-governed work enters AWAITING_APPROVAL.
Use CANCEL only when the definition declares a safe point. Use RETRY only when the failed Operation records retryable: true. Human governance clients use APPROVE, REJECT, or ROLLBACK; rejection requires a reason and rollback creates a new Candidate. CLAIM_SECRET is reserved for successful Operations that explicitly report a one-time secret claim.

Candidate inspection includes current-principal Approval/rejection eligibility, separate from the sealed document. Operation inspection includes publication-rollback eligibility. These are inspection-time guidance, not an authorization grant: every control request still rechecks authority and state. A distinct-approver requester may reject when authorized but cannot approve their own request. A Draft result is not a publication rollback target.

Review context can retain parent names and Field labels from the exact base. Policy proposals compare the retained policy value with the requested mode. Where available, inspection can also recover this context from an older Candidate’s retained base without rewriting its document or digest. Unavailable historical evidence remains explicitly unavailable; current live values are not substituted.

Agent-native Preview handoff

Inspect DELIVERY for Verified targets and the handoff descriptor. Propose and execute candidate_preview.create@1 with the exact Candidate ID/digest, target, and optional paired entity/type route context. Supply both route IDs or neither. The successful Operation retains only immutable provenance, expiry, and secretClaimAvailable: true. Call control_operation with CLAIM_SECRET using the same principal and credential, then return the claimed URL to the reviewer.

The link is a ten-minute, single-use read capability. Its confirmation page prevents ordinary link scanners from consuming it, then server-posts the bootstrap to the verified frontend. The reviewer needs no Jetrepo login, and the resulting website URL contains no credential. The capability cannot approve, execute, mutate, or publish. A stale Candidate, changed target, replay, expiry, different claimant credential, or narrowed delegated authority fails closed.

Delegated Delivery-key request

A delegated OAuth or Agent Auth client with live apiKey.create permission can propose organization_key.create@1 for a Delivery Published or Delivery Preview key. Its public schema enumerates delivery.readPublished and delivery.readPreview and the strict version-1 Backend/Environment scope object; do not invent a generic Delivery-read permission or extra scope dimensions. The definition has no resource projection, always requires human Approval, and rejects Agent-key configuration. Organization-owned Agent keys cannot discover, propose, execute, or claim this credential-creation flow.

The requesting delegated client executes the Candidate to create the Approval wait, returns its review link to a human, then observes the approved Operation until SUCCEEDED before calling control_operation with CLAIM_SECRET. Claim authorization is bound to the same principal and credential that created the Operation. The encrypted claim expires shortly and is deleted atomically on first successful consumption; replay, another credential, expiry, and unavailable claims return the same closed failure. Candidate, Operation, item outcome, and audit records retain only the key ID and secretClaimAvailable marker.

When the Draft head advances, Jetrepo compares the Candidate’s exact resource selectors with the new manifest under a locked head. Two agents changing disjoint resources serialize and both succeed; overlapping resources fail with deterministic HEAD drift evidence including the conflicting resource IDs. A stale revision on a selected resource, digest, dependency, permission, policy version, credential, cursor, or resource scope fails closed. Reread authoritative state and propose a new Candidate rather than overwriting overlap.

Publication and Approval

Publication policy inherits Environment override, then Backend default: AUTONOMOUS, APPROVAL_REQUIRED, or DISTINCT_APPROVER. An Operation Definition can strengthen this mode but cannot weaken it. The effective policy and version are sealed into the Candidate; a later policy change invalidates execution.

Only an authenticated human with operation.approve and the policy’s exact approver permission can approve or reject. Approval records the human, Candidate digest, policy and authorization versions, expiry, and reason. Distinct mode prevents the requester or delegating human from approving; authorized rejection remains available. An MCP client’s conversational confirmation or tool-approval prompt is never Jetrepo Approval.

Before consequential execution, the Worker claims a renewable PostgreSQL lease and monotonically increasing fence, then rechecks the credential, active Agent Auth capability grant, OAuth client, role, scopes, Candidate resources and dependencies, policy, and Approval. Item outcomes, quota consumption, transition, audit, and outbox evidence commit with authoritative state. Duplicate delivery is acknowledged from authoritative Operation state; a stale worker fence cannot commit twice.

A human with operation.rollback may act only while the successful Operation’s Published manifest remains current. Jetrepo compares retained immutable manifests and returns a distinct-approver Candidate containing exact reverse selectors. It never rewrites the original Operation or history.

Resources, subscriptions, and Tasks

Use stable jetrepo://management/... resources for the Change Set schema, Operation Definitions, Candidates, Operations, and exact per-Backend Delivery OpenAPI instead of copying large documents through repeated tool responses. inspect DELIVERY returns the OpenAPI resource URI and canonical hash plus REST, documentation, generation, batching, image, locale, Published provenance, and Preview readiness metadata. Reading the OpenAPI resource requires live Backend read access and never grants Delivery runtime access. Candidate and Operation subscriptions are hints: reread the resource after each notification. Subscriptions are bounded per credential and stop when authorization is revoked or narrowed.

Clients supporting MCP Tasks can project an existing Jetrepo Operation:

tasks/get reads authoritative status;
tasks/list returns Operations created by that principal with an opaque cursor;
tasks/cancel delegates to cooperative cancellation;
tasks/result reads terminal result and item outcomes.

Tasks never create work, own retention, replace the Operation record, or bypass policy. AWAITING_APPROVAL maps to input_required; queued/running/recovering work maps to working; terminal states map to completed, failed, or cancelled outcomes.

External-agent boundary

Registration provisions a Default Organization and session creation repairs that invariant before normal work. The activation flow connects the external agent in that Organization. The delegated agent discovers the Organization and creates the first Backend and main Environment through the same propose → execute sequence, then uses scoped Change Sets to construct the desired model, locales, Content, Assets, Taxonomy, integrations, and publication state. Jetrepo never receives a model-provider key.

Authoring and deletion definitions require a delegated human through Agent Auth or OAuth when their domain services resolve human authority. Organization-owned keys cannot receive those grants. entity.create_asset_with_fields@1 requires content.create and atomically creates one Draft Asset, applies its validated Field actions, and attaches one File previously uploaded under the same Backend and Asset type; any failure rolls back the Asset. asset.attach_file@1 remains the content.update path for an existing Asset. URL-based Asset import resolves and pins public DNS answers, rechecks each of at most three redirects, rejects private/special-use/metadata addresses and nonstandard ports, enforces a 20-second wall clock and 25 MiB streamed-byte ceiling, and validates declared media type against the bytes. A rejected origin, redirect, size, or type creates no Entity, File, or object.

Content and Asset metadata—including text that looks like instructions—remain untrusted values. Jetrepo runs no model over them, and they cannot change policy inputs, grant permissions, approve a Candidate, or invoke another tool. There is no SQL, shell, generic HTTP, database, raw mutation, conversational approval, or direct queue tool.