Skip to main content

​
Client API SDK Quickstart

This page is the SDK-first companion to /getting-started/client-api-quickstart. Internal beta distribution model: SDKs are shipped as GitHub Release artifacts (not npm/PyPI yet).

​
1. Prerequisites

  • OMNI Client API key (omni_live_*)
  • recommended scopes: mcp.tools.read, mcp.invoke, fred.read
  • GitHub CLI authenticated for artifact downloads

​
2. Install SDK artifacts

Artifacts are published in autonomous-computer/omni-system release tags: 
mcp-sdks-v*

​
JavaScript (pnpm)

gh release download mcp-sdks-v0.1.4-internal-beta \
  --repo autonomous-computer/omni-system \
  --pattern "*.tgz"

pnpm add ./*.tgz

​
Python (pip)

gh release download mcp-sdks-v0.1.4-internal-beta \
  --repo autonomous-computer/omni-system \
  --pattern "*.whl"

pip install ./*.whl

​
Integrity + compatibility artifacts (required)

gh release download mcp-sdks-v0.1.4-internal-beta \
  --repo autonomous-computer/omni-system \
  --pattern "SHA256SUMS" \
  --pattern "MCP_COMPATIBILITY_POLICY.md"

shasum -a 256 -c SHA256SUMS

​
3. Initialize, list tools, and call a tool

​
JavaScript

import crypto from "node:crypto";
import { OmniMcpClient } from "@omni/omni-mcp-js";

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

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

const idem = `idem_${crypto.randomUUID()}`;
const result = await client.callTool("fred.search", { q: "inflation", limit: 5 }, idem);
console.log(result.structuredContent);

​
Python

import os
import uuid

from omni_mcp_py import OmniMCPClient

client = OmniMCPClient(api_key=os.environ["OMNI_API_KEY"])

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},
    idempotency_key=f"idem_{uuid.uuid4()}",
)
print(result.get("structuredContent"))

​
Go (raw hosted MCP JSON-RPC)

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  payload := map[string]any{
    "jsonrpc": "2.0",
    "id":      1,
    "method":  "initialize",
    "params":  map[string]any{"protocolVersion": "2025-11-05"},
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("POST", "https://api.omnibrief.app/mcp", bytes.NewReader(body))
  req.Header.Set("Authorization", "Bearer "+os.Getenv("OMNI_API_KEY"))
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  raw, _ := io.ReadAll(resp.Body)
  fmt.Println(resp.StatusCode, string(raw))
}

​
4. Production retry wrappers

​
JavaScript (write-safe retry)

export async function callToolSafe(client: OmniMcpClient, name: string, arguments_: Record<string, unknown>) {
  const idem = `idem_${crypto.randomUUID()}`;
  const maxAttempts = 4;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    try {
      return await client.callTool(name, arguments_, idem);
    } catch (err: any) {
      const status = err?.status ?? err?.statusCode;
      const retryable = status === 429 || (typeof status === "number" && status >= 500);
      if (!retryable || attempt === maxAttempts) throw err;
      const delayMs = Math.min(250 * 2 ** (attempt - 1), 4000) + Math.floor(Math.random() * 250);
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }

  throw new Error("unreachable");
}

​
Python (write-safe retry)

import random
import time
import uuid


def call_tool_safe(client, name: str, arguments: dict):
    idem = f"idem_{uuid.uuid4()}"
    max_attempts = 4

    for attempt in range(1, max_attempts + 1):
        try:
            return client.call_tool(name=name, arguments=arguments, idempotency_key=idem)
        except Exception as exc:
            status = getattr(exc, "status_code", None)
            retryable = status == 429 or (isinstance(status, int) and status >= 500)
            if not retryable or attempt == max_attempts:
                raise
            delay = min(0.25 * (2 ** (attempt - 1)), 4.0) + random.uniform(0, 0.25)
            time.sleep(delay)

    raise RuntimeError("unreachable")

​
5. Conformance gate before promotion

For release tags, OMNI runs live conformance against hosted MCP. You should run equivalent checks in your rollout pipeline.

​
JS conformance

OMNI_CLIENT_API_BASE_URL=https://api.omnibrief.app \
OMNI_CLIENT_API_KEY=omni_live_... \
node sdk/omni-mcp-js/scripts/conformance.mjs

​
Python conformance

OMNI_CLIENT_API_BASE_URL=https://api.omnibrief.app \
OMNI_CLIENT_API_KEY=omni_live_... \
python sdk/omni-mcp-py/scripts/conformance.py

​
6. Non-optional production rules

  1. set explicit request timeouts
  2. retry only transient failures (429, 5xx)
  3. reuse idempotency keys for retried write-like calls
  4. log request ids and structured SDK error metadata
  5. verify artifact checksums before promotion
  6. track SDK version + compatibility policy version together

​
7. Release promotion checklist

  • download artifacts from approved tag
  • verify SHA256SUMS
  • verify MCP_COMPATIBILITY_POLICY.md
  • run smoke flow (initialize -> tools/list -> tools/call)
  • run conformance scripts
  • validate billing semantics in canary
  • /sources/client-api-sdks
  • /sources/client-api-mcp-compatibility
  • /sources/client-api-errors
  • /sources/client-api-retries