Web SDK

The web Assistant SDK is a set of npm packages under the @metabindai scope. The fastest path is @metabindai/agent-ui: a prebuilt React chat surface that streams from Metabind’s Agent proxy, calls your project’s tools, and renders Interactive Tool output in sandboxed iframes. Configure it with your project credentials and render <AgentChat /> — or drop to the lower-level typed streaming client and Vercel AI SDK transport when you want to build your own UI.

SDK on GitHub

metabind-web — the web Assistant SDK monorepo (Apache 2.0).

Example app

A minimal clone-and-run React chat app built on the published packages.

Packages

Package	What it gives you
`@metabindai/agent-ui`	The drop-in chat: `<AgentChat />`, the assistant-ui runtime, the agent transport, and MCP-UI tool rendering. Works standalone on a route or embedded in a host shell.
`@metabindai/agent-shell`	A host-side presentation shell — modal, sidebar, and pill — that embeds `<AgentChat />` in a same-origin iframe and surfaces its bridge signals as React callbacks.
`@metabindai/agent-ai-sdk`	A Vercel AI SDK adapter: `MetabindAgentTransport` drops into `useChat`, with an assistant-ui variant at `@metabindai/agent-ai-sdk/assistant-ui`.
`@metabindai/agent-core`	A framework-agnostic client that streams typed events from the Agent proxy. No React or AI SDK dependencies.

Requirements

React 18.3+ (react and react-dom are peer dependencies)
A Metabind project with published tools
A project-scoped Metabind API key

@metabindai/agent-ui and @metabindai/agent-shell ship as TypeScript source, so your bundler compiles them alongside your app. The example app uses Vite.

Start from the example app

The quickest way to a working chat is to copy the example app and point it at your project:

Copy the example app

npx degit metabindai/metabind-web/examples/example-metabind-react-app my-metabind-chat
cd my-metabind-chat
pnpm install

Get your credentials

You need an org ID, a project ID, and a project-scoped API key. The fastest path is the metabind CLI:

metabind auth login          # authenticate against your Metabind account
metabind use                 # bind to a project (or `metabind init` to create one)
metabind status              # read the bound projectId + orgId
metabind api-key create      # mint a project API key

Configure and run

Copy .env.example to .env.local, fill in VITE_METABIND_ORG_ID, VITE_METABIND_PROJECT_ID, and VITE_METABIND_API_KEY, then:

pnpm dev          # http://localhost:5173

There’s no server-side code in the app — the Agent proxy is the backend.

Add the chat to an existing app

Install

pnpm add @metabindai/agent-ui react react-dom

npm install @metabindai/agent-ui react react-dom

Serve the sandbox proxy

Copy sandbox_proxy.html from the package’s public/ folder into wherever your app serves static files. Interactive Tool UIs render inside it. If you serve it somewhere other than /sandbox_proxy.html, point configureChat({ sandboxUrl }) at it.

Configure and render

Call configureChat once, before <AgentChat /> mounts, and import the prebuilt stylesheet at your app’s entry point:

import { AgentChat, configureChat, DefaultWelcome } from "@metabindai/agent-ui";

configureChat({
  agent: {
    orgId: import.meta.env.VITE_METABIND_ORG_ID,
    projectId: import.meta.env.VITE_METABIND_PROJECT_ID,
    apiKey: import.meta.env.VITE_METABIND_API_KEY,
  },
  sandboxUrl: "/sandbox_proxy.html",
  welcome: () => (
    <DefaultWelcome
      title="How can I help?"
      subtitle="Ask me anything — I can use the tools wired to this project."
    />
  ),
});

export default function App() {
  return <AgentChat />;
}

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "@metabindai/agent-ui/agent-ui.css";
import App from "./app.tsx";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

Prefer an imperative mount? mountAgentChat(el, config) calls configureChat for you and returns an unmount cleanup.

`configureChat` options

Option	Default	Description
`agent.orgId` / `agent.projectId` / `agent.apiKey`	required	Your Metabind project and a project-scoped API key. `apiKey` is a string or a sync/async getter, so a backend can broker short-lived tokens.
`agent.baseUrl`	`https://agent.metabind.ai`	The Agent proxy endpoint.
`agent.draft`	`false`	Target the project’s draft (unpublished) tools instead of the published ones.
`mcp.baseUrl`	`https://mcp.metabind.ai`	The hosted MCP server endpoint.
`sandboxUrl`	`/sandbox_proxy.html`	Path or URL to the sandbox proxy you serve.
`welcome`	built-in `<DefaultWelcome />`	Render function for the empty state. Can use `StarterTile` for clickable starter prompts.
`autoStart`	`true`	Open the conversation with a hidden opener turn so the agent speaks first, driven by its system prompt. Set `false` to keep the welcome state.
`debug`	`false`	Show the developer tool-call display (raw arguments and results). `?debug=1` overrides at runtime.
`allowAttachments`	`false`	Allow attaching media and files in the composer.
`tracer`	—	Per-turn tracing hook for analytics.

How Interactive Tools render on the web

When the agent calls an Interactive Tool, @metabindai/agent-ui fetches the tool’s UI resource from your project’s MCP server and renders it inside a sandboxed iframe through MCP-UI (@mcp-ui/client), hosted by the sandbox_proxy.html you serve. This is the same isolation model MCP hosts like Claude and ChatGPT use on the web: tool UIs can’t touch your page’s DOM, storage, or credentials. This differs from the iOS SDK and Android SDK, where the same tool definitions render as SwiftUI and Jetpack Compose. On the web, rendering is web technology in an isolated sandbox. To present the chat over an existing page rather than on its own route, add @metabindai/agent-shell. It renders a single panel that morphs between a centered modal, a docked sidebar, and a minimized pill, and embeds <AgentChat /> in a same-origin iframe so the chat’s CSS stays isolated from your page.

pnpm add @metabindai/agent-shell @metabindai/agent-ui react react-dom

Serve <AgentChat /> at a same-origin route (for example /chat), then point the shell at it:

import { useAgentShell, AgentShell } from "@metabindai/agent-shell";

function Page() {
  const chat = useAgentShell({
    chatUrl: "/chat",
    context: { systemContext: "The user is on the pricing page." },
    onSignal: (s) => console.log("bridge", s),
  });

  return (
    <>
      <button ref={chat.launchRef} onClick={chat.launch}>
        Ask the assistant
      </button>
      <AgentShell {...chat.shellProps} />
    </>
  );
}

useAgentShell owns open/close state, the launch-element ref (the panel grows out of it), and the iframe bridge, so you don’t wire postMessage by hand. The shell seeds conversation context into the chat on load and surfaces a tool’s dock requests as React callbacks.

Build your own UI

If <AgentChat /> doesn’t fit, the two lower-level packages give you the same streaming pipeline without the prebuilt chat.

With the Vercel AI SDK

MetabindAgentTransport from @metabindai/agent-ai-sdk drops into useChat from @ai-sdk/react. It reshapes outbound messages to the proxy’s request format and translates the inbound stream into the chunks the AI SDK expects — tools are marked as already executed by the proxy.

import { useChat } from "@ai-sdk/react";
import { MetabindAgentTransport } from "@metabindai/agent-ai-sdk";

const transport = new MetabindAgentTransport({
  orgId: "my-org",
  projectId: "oak-and-ivory",
  apiKey: projectToken,
});

function Chat() {
  const { messages, sendMessage } = useChat({ transport });
  // render messages; call sendMessage to send a turn
}

ai and @ai-sdk/react are peer dependencies you provide. For an assistant-ui runtime, import the transport from @metabindai/agent-ai-sdk/assistant-ui instead (which also needs @assistant-ui/react-ai-sdk).

Framework-agnostic streaming

@metabindai/agent-core is a typed client for the Agent proxy with no React or AI SDK dependencies. client.chat(...) returns an async iterable of discriminated events — text deltas, tool calls, tool results, and turn boundaries:

import { createAgentClient } from "@metabindai/agent-core";

const client = createAgentClient({ orgId, projectId, apiKey });

for await (const event of client.chat({
  messages: [{ role: "user", content: "What's in stock?" }],
})) {
  // event.type: "text_delta" | "tool_use" | "tool_result" | "message_stop" | ...
}

The client also exposes chatText(...) (collects a full text response) and fetchChat(...) (the raw Response, for custom parsers).

Key custody

The web SDK talks only to the Agent proxy — there’s no bring-your-own-key provider on the web. The proxy holds the LLM key and runs the tool loop server-side, so no LLM-provider credential ever reaches the browser. See LLM provider configuration.

Your Metabind API key is inlined into the browser bundle — the same exposure profile as a Bearer header on every request. That’s acceptable for a project-scoped Metabind key, never for raw LLM-provider secrets. For tighter control, pass agent.apiKey as an async getter and have your backend mint short-lived tokens.

Styling

The chat is styled with Tailwind v4, but your app doesn’t need Tailwind: import the self-contained prebuilt stylesheet the package compiles at build time.

import "@metabindai/agent-ui/agent-ui.css";

It includes a CSS reset, so load it only on the route that serves the chat — or embed the chat through @metabindai/agent-shell, which isolates it inside an iframe. If your app is on Tailwind v4 and you want to theme the chat with your own tokens, compile it from source instead — see the @metabindai/agent-ui README.

Assistant SDK overview

Conceptual: when to embed vs. connect to an external host.

LLM provider configuration

How the Agent proxy holds keys and runs the tool loop.

iOS SDK

The same agent rendered as SwiftUI.

Android SDK

The same agent rendered as Jetpack Compose.

Getting Started

Core Concepts

Building Your MCP App

Publishing

Connecting to MCP Hosts

Assistant SDK

Operations

Sample Apps

SDK on GitHub

Example app

Packages

Requirements

Start from the example app

Add the chat to an existing app

Install

Serve the sandbox proxy

Configure and render

`configureChat` options

How Interactive Tools render on the web

Build your own UI

With the Vercel AI SDK

Framework-agnostic streaming

Key custody

Styling

Assistant SDK overview

LLM provider configuration

iOS SDK

Android SDK

SDK on GitHub

Example app

​Packages

​Requirements

​Start from the example app

​Add the chat to an existing app

​Install

​Serve the sandbox proxy

​Configure and render

​configureChat options

​How Interactive Tools render on the web

​Embed as a modal, sidebar, or pill

​Build your own UI

​With the Vercel AI SDK

​Framework-agnostic streaming

​Key custody

​Styling

​Related

Assistant SDK overview

LLM provider configuration

iOS SDK

Android SDK

Packages

Requirements

Start from the example app

Add the chat to an existing app

Install

Serve the sandbox proxy

Configure and render

`configureChat` options

How Interactive Tools render on the web

Embed as a modal, sidebar, or pill

Build your own UI

With the Vercel AI SDK

Framework-agnostic streaming

Key custody

Styling

Related