Platform

gRPC Transport Guide

When to use gRPC vs HTTP, endpoint configuration, TLS, and proto file locations for MuBit SDKs.

MuBit supports both HTTP/REST and gRPC transports. All SDK methods work identically regardless of transport — the choice affects performance characteristics, not API surface.

When to use gRPC vs HTTP

Factor	gRPC	HTTP
Latency	Lower per-call overhead (binary protocol, persistent connections)	Slightly higher due to JSON serialization
Streaming	Native bidirectional streaming (`Subscribe`, `StreamSearch`, `WatchMemory`)	SSE for events, no bidirectional streaming
Debugging	Requires gRPC tooling (grpcurl, Bloom RPC)	curl, browser dev tools
Proxies/CDNs	Requires HTTP/2-aware infrastructure	Works everywhere
Browser clients	Requires grpc-web proxy	Native fetch/XMLHttpRequest

Recommendation: Use gRPC for backend services where you want lower latency and streaming. Use HTTP for browser clients, serverless functions, or environments with HTTP/1.1-only proxies.

Configuration

Environment variables

.env

MUBIT_TRANSPORT="grpc"
MUBIT_GRPC_ENDPOINT="grpc.api.mubit.ai:443"

SDK constructor

from mubit import Client
 
client = Client(
    api_key="mbt_...",
    transport="grpc",
    # endpoint defaults to grpc.api.mubit.ai:443
)

Endpoints

Environment	gRPC endpoint	TLS
Hosted (production)	`grpc.api.mubit.ai:443`	Yes (system CA)
Hosted (dev)	`grpc.api.dev.mubit.ai:443`	Yes (system CA)
Local	`127.0.0.1:50051`	No (plaintext)

TLS is handled automatically by the SDK — no certificate configuration is needed for hosted endpoints.

Proto file locations

The proto definitions are available in the repository:

Proto file	Service	Description
`proto/mubit/v1/core.proto`	`CoreService`	Core data-plane operations (insert, search, memory, sessions)
`proto/mubit/v1/control.proto`	`ControlService`	Control-plane operations (ingest, query, context, reflection, coordination)

These can be used with any gRPC code generator if you need a client outside the official SDKs.

Streaming RPCs

gRPC enables streaming RPCs not available over HTTP:

RPC	Direction	Purpose
`Subscribe` (Control)	Server → Client	Stream control-plane events in real-time
`StreamSearch` (Core)	Server → Client	Stream search results as they're found
`WatchMemory` (Core)	Server → Client	Watch for scratchpad memory changes

import json
 
# Stream control events — each yielded item is a raw line from the event stream
for line in client.advanced.subscribe(run_id="my-run"):
    if not line:
        continue
    event = json.loads(line)
    print(f"Event: {event['type']} — {event['data']}")

Auto transport

When transport is set to "auto" (the default), the SDK:

Checks if a gRPC connection can be established to the endpoint
Falls back to HTTP if gRPC is unavailable
Caches the result for subsequent calls

This works well for most deployments. Set an explicit transport when you need deterministic behavior or want to avoid the initial probe.

Troubleshooting

Symptom	Cause	Fix
Connection refused on port 50051	gRPC server not running or wrong endpoint	Verify endpoint; for local, ensure `make run-mubit` is running
TLS handshake failure	Self-signed cert or wrong CA	For hosted endpoints, ensure system CA store is current
`UNIMPLEMENTED` error	Proto version mismatch	Update SDK to latest version
`DEADLINE_EXCEEDED`	Network timeout	Check connectivity; increase timeout in client config
Fields missing in response	`keepCase` not set (JS SDK < v0.4.1)	Update `@mubit-ai/sdk` to >= v0.4.1

Next steps

See SDK Configuration Reference for all config options.
See Control gRPC reference for the full RPC surface.