Skip to main content

​
Hosted MCP Compatibility Policy

This policy defines what is stable, what can change, and how breaking evolution is handled for hosted MCP.

​
Canonical endpoints

  • Primary: https://api.omnibrief.app/mcp
  • SSE compatibility: https://api.omnibrief.app/sse

​
Protocol negotiation and supported versions

OMNI negotiates protocol on initialize.
  • Requested supported version: echoed in result.protocolVersion
  • Requested unsupported version: server falls back to default supported version
Supported versions (internal beta):
  • 2025-11-05 (default)
  • 2025-06-18
  • 2025-03-26

​
Stability classes

SurfaceStability classNotes
/mcp JSON-RPC transportStableCanonical endpoint for MCP integrations
/sse transportCompatibilityMaintained for client compatibility; /mcp is preferred
initialize, notifications/initialized, ping, tools/list, tools/callStableMethod semantics are contract-protected
tool identifiers (fred.search, fred.series)StableBreaking changes require new identifier

​
Tool evolution rules

Non-breaking:
  • add optional fields to inputSchema
  • expand result payload with additive fields
Breaking:
  • remove required field
  • change meaning of existing field
  • repurpose tool behavior
Breaking changes require:
  1. new tool identifier (for example fred.search.v2)
  2. migration guide + changelog entry
  3. sunset window for prior identifier

​
Idempotency and billing parity

tools/call requires: 
Idempotency-Key: idem_...
Parity guarantees with Client API:
  • same auth + scope model
  • same rate limits + request IDs
  • same error semantics (omni_code mapping)
  • same billable semantics: first successful write-like operation only

​
SDK compatibility matrix (internal beta)

SDK lineDistributionSupported MCP protocol versions
omni-mcp-js 0.1.xGitHub Release .tgz artifact2025-11-05, 2025-06-18, 2025-03-26
omni-mcp-py 0.1.xGitHub Release .whl/.tar.gz artifacts2025-11-05, 2025-06-18, 2025-03-26
Release integrity artifacts:
  • SHA256SUMS
  • MCP_COMPATIBILITY_POLICY.md

​
Compatibility lifecycle policy

  • additive protocol/tool changes: allowed without breaking notice
  • behavioral non-breaking changes: changelog + rationale
  • deprecations: minimum 180-day target sunset window
  • breaking changes: minimum 90-day migration window after replacement is live

​
Conformance gating

Every SDK release tag (mcp-sdks-v*) is gated by live conformance checks against https://api.omnibrief.app/mcp:
  • JS: sdk/omni-mcp-js/scripts/conformance.mjs
  • Python: sdk/omni-mcp-py/scripts/conformance.py
Required successful sequence:
  1. initialize
  2. tools/list includes fred.search
  3. tools/call returns structured content
  • /sources/client-api-mcp-hosted
  • /sources/client-api-sdks
  • /getting-started/client-api-sdk-quickstart
  • /sources/client-api-migrations