Skip to main content

Connect an application

Use connect() when an operator owns the Mecatl daemon and your application owns only the client connection. Node.js and Bun connect to the gRPC listener. Browser applications connect to the HTTP and SSE API through a same-origin backend-for-frontend (BFF).

Connect from Node.js or Bun​

Import connect() from the Node.js and Bun entry point, then pass the gRPC listener's HTTP or HTTPS authority:

import { connect } from "@stacklok-oss/mecatl-sdk/node";

const client = connect({
  baseUrl: process.env.MECATL_URL ?? "http://127.0.0.1:8080",
});

try {
  const session = await client.sessions.create({});
  const result = await (await session.run("Summarize this repository")).result();
  console.log(result.text);
} finally {
  await client.close();
}

Pass fixed request headers with headers:

const token = process.env.MECATL_TOKEN;
if (token === undefined) throw new Error("MECATL_TOKEN is required");

const client = connect({
  baseUrl: "https://mecatl.example.com",
  headers: { authorization: `Bearer ${token}` },
});

Use credentialProvider instead when the application refreshes credentials. The SDK calls the provider for every request and does not persist its returned headers.

Connect from a browser​

Import from the transport-neutral entry point and use the BFF's same-origin path:

import { connect } from "@stacklok-oss/mecatl-sdk";

await using client = connect({
  baseUrl: "/mecatl",
  credentials: "include",
});

const session = await client.sessions.create({});
const result = await (await session.run("Explain the selected file")).result();
console.log(result.text);

The BFF must inject the daemon credential and enforce Origin and CSRF policy. Keep privileged daemon credentials out of browser JavaScript. The SDK supplies the browser-facing HTTP and SSE client; it does not include a BFF server.

For local browser development, an operator can configure the daemon's exact CORS origins. See Drive Mecatl through gRPC or HTTP for listener and transport configuration.

Observe connection status​

client.status is a multicast status store. Read the current value with getSnapshot() or subscribe to changes:

const unsubscribe = client.status.subscribe((status) => {
  console.log("Mecatl connection:", status);
});

unsubscribe();

The status vocabulary is connecting, online, reconnecting, offline, unauthorized, and incompatible.

Next steps​