Skip to main content

​
Client API SDKs

During internal beta, OMNI ships official SDK adapters as GitHub Release artifacts (not npm / PyPI yet). These SDKs are intentionally thin wrappers over the hosted MCP endpoint (/mcp) so:
  • auth, rate limits, usage metering, and error semantics match the raw HTTP contract
  • you can always drop down to raw HTTP without changing your integration model

​
SDK-first posture (how to build with OMNI like you would with Stripe)

Recommendations:
  • Treat the SDK as a convenience layer, not a separate product.
  • Model your integration around: key scopes, request IDs (X-Request-Id), idempotency for side-effecting operations (tools/call), and explicit timeouts + retries.
For retry behavior, see /sources/client-api-retries. If you want a runnable, end-to-end “first call” flow, start with:
  • /getting-started/client-api-sdk-quickstart

​
Where to get builds

SDK artifacts are published as assets on tagged GitHub Releases in autonomous-computer/omni-system. Look for tags with the prefix: 
mcp-sdks-v*
Current validated internal-beta release: 
mcp-sdks-v0.1.4-internal-beta
Each release ships:
  • JS package artifact (*.tgz)
  • Python artifacts (*.whl, *.tar.gz)
  • SHA256SUMS
  • MCP_COMPATIBILITY_POLICY.md

​
Versioning and compatibility (internal beta)

  • Adapter versions follow semver.
  • A given adapter version may support multiple MCP protocol versions; see /sources/client-api-mcp-compatibility.
  • During internal beta, we may publish quickly; you should pin the adapter version in production-like integrations.

​
Hosted MCP SDKs

​
JavaScript: @omni/omni-mcp-js (internal beta)

Install from a GitHub Release .tgz asset: 
# Option A: download the .tgz and install from disk
pnpm add ./omni-omni-mcp-js-<version>.tgz
Usage: 
import { OmniMcpClient } from "@omni/omni-mcp-js";

const client = new OmniMcpClient({
  apiKey: process.env.OMNI_API_KEY!,
  // baseUrl: "https://api.omnibrief.app",
  // timeoutMs: 20000,
});

await client.initialize();

const tools = await client.listTools();
console.log(tools.tools.map((t) => t.name));

const result = await client.callTool(
  "fred.search",
  { q: "inflation", limit: 5 },
  `idem_${Date.now()}`,
);

console.log(result.structuredContent);
Notes:
  • tools/call requires Idempotency-Key for safe retries; pass it as the third argument to callTool.
  • Errors throw OmniMcpError with structured metadata (kind, status, requestId, rpcCode, data).

​
Quickstart: robust invocation wrapper (TypeScript)

import crypto from "node:crypto";

export async function callFredSearch(client: OmniMcpClient, q: string) {
  const idem = `idem_${crypto.randomUUID()}`;
  try {
    return await client.callTool("fred.search", { q, limit: 5 }, idem);
  } catch (err) {
    // Surface idempotency key and request ids in your logs for supportability.
    console.error("omni mcp call failed", { idem, err });
    throw err;
  }
}

​
Python: omni-mcp-py (internal beta)

Install from a GitHub Release wheel (.whl) or source distribution (.tar.gz): 
# Option A: download the wheel and install from disk
pip install ./omni_mcp_py-<version>-py3-none-any.whl
Usage: 
from omni_mcp_py import OmniMCPClient, OmniMCPError

client = OmniMCPClient(api_key="omni_live_...")

client.initialize()

tools = client.list_tools()
print([t["name"] for t in tools.get("tools", [])])

result = client.call_tool(
    name="fred.search",
    arguments={"q": "inflation", "limit": 5},
)

print(result.get("structuredContent"))
Notes:
  • call_tool auto-generates an idempotency key if you do not provide one.
  • Errors raise OmniMCPError with structured metadata (kind, status_code, request_id, rpc_code, data).

​
Roadmap (public-beta-ready)

  • publish packages to npm / PyPI with stable versioning guarantees
  • typed error classes with status, requestId, and omni_code
  • first-party integration templates (Next.js, FastAPI, Rails)