gRPC Transport Guide

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

Python
Node / TS
Rust

from mubit import Client

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

import { Client } from "@mubit-ai/sdk";

const client = new Client({
  api_key: "mbt_...",
  transport: "grpc",
  // endpoint defaults to grpc.api.mubit.ai:443
});

use mubit_sdk::{Client, ClientConfig};

let config = ClientConfig::new("grpc.api.mubit.ai:443")
    .api_key("mbt_...")
    .transport("grpc");
let client = Client::connect(config).await?;

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`	`MubitService`	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

Python
Node / TS
Rust

# Stream control events
async for event in client.control.subscribe(run_id="my-run"):
    print(f"Event: {event.type} — {event.data}")

// Stream control events
for await (const event of client.control.subscribe({ runId: "my-run" })) {
  console.log(`Event: ${event.type} — ${event.data}`);
}

// Stream control events
let mut stream = client.control().subscribe("my-run").await?;
while let Some(event) = stream.next().await {
    println!("Event: {} — {}", event.r#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.

Overview

Learn the basics

Build with MuBit

Go deeper

Platform

Help

gRPC Transport Guide

When to use gRPC vs HTTP

Configuration

Environment variables

SDK constructor

Endpoints

Proto file locations

Streaming RPCs

Auto transport

Troubleshooting

Next steps

Overview

Learn the basics

Build with MuBit

Go deeper

Platform

Help

​When to use gRPC vs HTTP

​Configuration

​Environment variables

​SDK constructor

​Endpoints

​Proto file locations

​Streaming RPCs

​Auto transport

​Troubleshooting

​Next steps

When to use gRPC vs HTTP

Configuration

Environment variables

SDK constructor

Endpoints

Proto file locations

Streaming RPCs

Auto transport

Troubleshooting

Next steps