Compatibility and versioning

Stable surfaces

• MCP endpoint: https://elicitra.eigen.rest/api/mcp.
• Scenario export format: elicitra.scenario.v1.
• Webhook event types end in .v1.
• The current machine contract lives under /developers/v6/ and is byte-immutable after publication.
• The previous /developers/v1/, /developers/v2/, /developers/v3/, /developers/v4/, and /developers/v5/ trees remain available and byte-immutable; no sunset is currently scheduled.
• Webhook contracts are published as AsyncAPI 3.0.0 (document version 1.1.0).

MCP protocol negotiation is separate from Elicitra contract versioning. The hosted server is stateless: it creates a fresh protocol server per POST and never returns Mcp-Session-Id.

Every published version tree is immutable. Consumers should ignore unknown JSON object properties when reading output, but must send inputs that match the current published closed schemas. Any contract-field addition is published under a parallel version before runtime starts returning it.

The unversioned MCP endpoint advertises and serves the v6 MCP runtime contract with the same fourteen-tool allowlist. Both initialize.serverInfo.version and elicitra_get_started.contractVersion are v6. Versioned directories are pinned machine artifacts, not alternate MCP routes. Webhook event type suffixes (.v1), HMAC signature entries (v1=), and the elicitra.scenario.v1 export format are independent protocols.

The assistant-name schema addition and fourth public event required the parallel v6 artifact tree because v5 is immutable. V6 keeps the three lifecycle subscriptions unchanged while adding the non-subscribable com.elicitra.automation.triggered.v1 conditional-destination event; the hosted MCP runtime migrated to v6 only after that parallel tree was available.

Existing lifecycle deliveries remain pinned to their v5 dataschema URLs, so a consumer that validates the immutable URL continues to receive the same contract. Only com.elicitra.automation.triggered.v1 uses the new v6 dataschema; the v6 tree also republishes the unchanged lifecycle schemas for discovery.

The versioned manifest.json publishes a deterministic sha256: digest for every MCP input/output and webhook data schema. Consumers can use those hashes to pin reviewed contracts and detect accidental artifact drift.

An incompatible change introduces a parallel version. Elicitra retains the previous public tool/event artifacts for at least 180 days. If a version is deprecated, its deprecation and sunset dates are published here and in the changelog before removal.

Client support

Elicitra tests the current stable Codex CLI/IDE extension, Claude Code, and Cursor against staging before GA and after transport changes. A client is listed as supported only if it can:

1. send an environment-backed bearer token;
2. negotiate stateless Streamable HTTP without GET/session requirements;
3. list the correct scope-filtered tools;
4. complete the draft workflow without storing the PAT in the project.

If a client release cannot meet those invariants, the release is marked temporarily unsupported; Elicitra does not weaken tenant, auth, or stateless transport controls to accommodate it.