Skip to main content

​
Client API Migrations

This page defines the migration contract for OMNI Client API and hosted MCP. Treat this as the policy source for production integrations.

​
Migration north stars

  1. additive-first evolution
  2. no hidden breaking behavior on pinned versions
  3. write safety through idempotency
  4. stable request correlation via request IDs

​
Lifecycle guarantees (v1.5)

Change typeCompatibility guaranteeCommunication requirementMinimum window
AdditiveBackward compatibleChangelog entrynone
Behavioral (non-breaking)Existing shape preservedChangelog + rationale14 days recommended
DeprecationDeprecated route/tool remains functional during sunsetDeprecation + Sunset headers + migration guide180 days target
BreakingRequires new versioned surface (endpoint/tool/version)Changelog + migration guide + compatibility update90 days target after replacement launch

​
Version pinning policy (Omni-Version)

Pin every production integration: 
Omni-Version: 2026-02-18
Upgrade sequence:
  1. review changelog and migration notes
  2. run integration tests against target pin
  3. canary by key/environment
  4. monitor error and billing drift
  5. promote gradually
  6. retain rollback pin until stability clears

​
Deprecation/sunset policy

Required deprecation headers: 
Deprecation: true
Sunset: 2026-08-31T00:00:00Z
Link: </sources/client-api-mcp-hosted>; rel="successor-version"
Timeline template:
  • T-90: announce replacement + migration guide
  • T-60: surface usage warnings and outreach
  • T-30: enforce deprecation headers broadly
  • T-7: block new dependencies on deprecated path
  • T-0: sunset only after migration SLO gates pass

​
Migration guide: legacy MCP routes -> hosted MCP

Legacy routes:
  • GET /v1/mcp/tools
  • POST /v1/mcp/invoke
Canonical replacement:
  • POST /mcp (tools/list, tools/call)
Mapping:
LegacyHosted MCP
GET /v1/mcp/toolsPOST /mcp with method=tools/list
POST /v1/mcp/invokePOST /mcp with method=tools/call
Required hosted MCP sequence:
  1. initialize
  2. notifications/initialized
  3. tools/list
  4. tools/call
Non-negotiable checks:
  • Idempotency-Key on all tools/call
  • scopes include mcp.tools.read, mcp.invoke, and tool scopes (for example fred.read)
  • retry policy updated for JSON-RPC categories
  • logs capture error.data.request_id

​
Migration guide: unscoped keys -> scoped keys

Recommended minimum scope set for MCP + FRED: 
["mcp.tools.read", "mcp.invoke", "fred.read"]
If you receive 403 insufficient_scope, debug in order:
  1. assigned key scopes
  2. Omni-Required-Scopes header
  3. method/tool contract

​
Rollback criteria (mandatory)

Rollback immediately if sustained:
  1. auth/scope spike (401/403)
  2. idempotency conflict spike (409)
  3. invoke/internal failure spike (mcp_invocation_failed, mcp_internal_error)
  4. billing drift vs expected units

​
Migration completion checklist

  • endpoint/tool mapping validated
  • scope model updated and tested
  • idempotency replay behavior validated
  • request-id propagation validated end-to-end
  • retry policy aligned to /sources/client-api-retries
  • billing semantics validated for success/failure/replay
  • rollback owner + trigger documented
  • /sources/client-api-reference
  • /sources/client-api-changelog
  • /sources/client-api-errors
  • /sources/client-api-mcp-hosted
  • /sources/client-api-mcp-compatibility