Skip to main content

​
Hosted MCP Protocol

OMNI’s official hosted MCP endpoint is: 
https://api.omnibrief.app/mcp
Compatibility endpoint: 
https://api.omnibrief.app/sse
If you want a compact endpoint catalog, see:
  • /sources/client-api-reference
  • /sources/client-api-endpoints

​
Transport model

  • Primary: streamable HTTP (/mcp)
  • Compatibility: SSE (/sse) for clients expecting legacy event stream bootstrap

​
Authentication

All requests require: 
Authorization: Bearer omni_live_...
For tools/call, include: 
Idempotency-Key: <unique-per-call>
Recommended: 
X-Request-Id: req_...

​
Supported methods

MethodDescription
initializeHandshake and capability negotiation.
pingConnectivity health check.
tools/listEnumerate OMNI MCP tools.
tools/callInvoke a specific tool with arguments.
notifications/initializedInitialization notification (no id).

​
Example sequence

  1. initialize
  2. notifications/initialized
  3. tools/list
  4. tools/call

​
JSON-RPC request/response shape

Requests are JSON: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
Responses are either:
  • a result object, or
  • an error object
OMNI always includes an HTTP X-Request-Id header on responses, and hosted MCP errors also include error.data.request_id for correlation.

​
initialize

Minimal example: 
curl -X POST "https://api.omnibrief.app/mcp" \
  -H "Authorization: Bearer omni_live_..." \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: req_mcp_init_001" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-05",
      "clientInfo": {"name": "example", "version": "0.0.1"},
      "capabilities": {}
    }
  }'
Notes:
  • OMNI may select a different protocol version if you request an unsupported one; see /sources/client-api-mcp-compatibility.
  • After initialize, send notifications/initialized (no id) before tool calls.

​
tools/list

curl -X POST "https://api.omnibrief.app/mcp" \
  -H "Authorization: Bearer omni_live_..." \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: req_mcp_tools_001" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
Typical required scope: 
mcp.tools.read

​
tools/call

tools/call is side-effecting in the general case and requires idempotency. 
curl -X POST "https://api.omnibrief.app/mcp" \
  -H "Authorization: Bearer omni_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_mcp_call_001" \
  -H "X-Request-Id: req_mcp_call_001" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "fred.search",
      "arguments": { "q": "inflation", "limit": 5 }
    }
  }'
Required scopes:
  • mcp.invoke
  • tool-specific scope (example: fred.read)
If you retry a tools/call due to timeout or transient failure, retry with the same Idempotency-Key.

​
Error behavior (hosted MCP)

Hosted MCP errors are JSON-RPC compliant and include omni_code for mapping into REST-style error handling. Example (shape only): 
{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32001,
    "message": "Unauthorized",
    "data": {
      "omni_code": "invalid_api_key",
      "request_id": "req_123"
    }
  }
}
See /sources/client-api-errors for JSON-RPC code mappings and retry guidance.

​
Tool parity policy

Hosted MCP tool behavior maps to OMNI Client API semantics:
  • same auth model
  • same rate limits and quotas
  • same request ID behavior
  • same billing semantics (2xx/3xx billable, failures non-billable)

​
Current tools

  • fred.search
  • fred.series

​
Session behavior

  • MCP-Session-Id header is returned for hosted transport sessions.
  • DELETE /mcp closes the active session context.
See /sources/client-api-mcp-compatibility for protocol and tool compatibility guarantees.

​
Official adapters (internal beta)

During internal beta, OMNI provides first-party adapters to make MCP integration straightforward. These adapters are not published to npm/PyPI yet. For internal beta they are distributed as GitHub Release artifacts from the omni-system repo, gated by live conformance against https://api.omnibrief.app/mcp.

​
JavaScript (@omni/omni-mcp-js)

Download and install (internal beta): 
gh release download mcp-sdks-v0.1.4-internal-beta \
  --repo autonomous-computer/omni-system \
  --pattern "*.tgz"

pnpm add ./*.tgz
Usage: 
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",
});

await client.initialize();

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

​
Python (omni-mcp-py)

Download and install (internal beta): 
gh release download mcp-sdks-v0.1.4-internal-beta \
  --repo autonomous-computer/omni-system \
  --pattern "*.whl"

pip install ./*.whl
Usage: 
from omni_mcp_py import OmniMCPClient, OmniMCPError

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

client.initialize()

try:
    result = client.call_tool(
        name="fred.search",
        arguments={"q": "inflation", "limit": 5},
        idempotency_key="idem_example_001",
    )
    print(result.get("structuredContent"))
except OmniMCPError as exc:
    print(str(exc))
    raise

​
Availability

These adapters are currently available to internal beta customers. If you do not have access, use the raw HTTP examples above and request adapter access when it becomes available for your account.