Skip to main content
The Assistant SDK is the embed path for Metabind. It packages an MCP-aware AI client, conversation state, and rendering of Interactive Tool output into a single SDK you drop into your app. Configure how it should reach an LLM, give it a host surface, and the SDK handles the rest.

​
A governed agent inside your own app

Most “drop-in AI” SDKs route your users to someone else’s chat surface, someone else’s brand, and someone else’s tool ecosystem. The Assistant SDK is the opposite — a governed agent runs inside your product, calling tools you built in Metabind, rendered with your components, on your typography and color. It follows your project instructions and renders only your approved components. Your users never leave your app, and you never hand them off to a third-party host.
Rendered Interactive Tool components — product detail cards, a purchasable item card with Buy Now, a 3D model viewer chip, and a product-comparison view — all returned by AI tool calls and rendered as native UI.

​
What the SDK gives you

The Assistant SDK sits between your app's UI and rendered native UI. It packages an MCP client, LLM provider, conversation manager, and native renderer.
The result: your users get a chat-like assistant that can call your Metabind tools and render the results with your approved components — no rebuild for layout changes, no release cycle when you add a tool. On mobile, rendering is real native — SwiftUI and Jetpack Compose, not web views.

​
Use the Assistant SDK when

  • You’re building an iOS, Android, or web product and want an in-product assistant.
  • You want to ship MCP tools that you built (in Metabind) without exposing a third-party MCP host to your users.
  • You want tool results rendered as interactive UI — SwiftUI on iOS, Jetpack Compose on Android, and sandboxed web UI inside your React app.
  • You want Metabind to manage LLM key custody and the tool loop server-side (the default).

​
Use a connected MCP host instead when

  • Your users already work in Claude Desktop or ChatGPT, and you want to extend those surfaces.
  • You don’t want to ship a UI yourself — connecting to an existing host is faster.
  • The use case is developer-facing rather than end-user-facing.
A project’s tools work in both modes simultaneously. You can ship an Assistant SDK in your app and let power users also connect Claude Desktop to the same project.

​
Three platforms, one model

On iOS and Android, the SDK ships MetabindAssistant plus a drop-in MetabindAssistantView chat surface. On the web, @metabindai/agent-ui ships the drop-in <AgentChat /> React component. For working references, see the iOS assistant demo, the Android assistant demo, and the web example app.

​
Two ways to reach an LLM

The SDK reaches an LLM in one of two ways:
  • The Agent proxy at agent.metabind.ai — MetabindAgentProvider on iOS and Android; on the web, <AgentChat /> and the lower-level clients talk to the proxy directly. The proxy authenticates with a Metabind project token, holds the LLM key, runs the tool loop server-side, and streams responses back as SSE. The proxy supports Anthropic, OpenAI, and Google — selected per-project in Metabind Studio. Available on all three platforms; recommended for production.
  • AnthropicProvider (iOS) — bring-your-own-key (BYOK) Anthropic, called directly from the client. Useful for development, internal tools, or apps where the key reaches the SDK from an authenticated user-managed source.
On iOS, custom providers can implement the public LLMProvider protocol if you need to integrate something else. See LLM provider configuration.

​
What you bring

  • A Metabind project with at least one published Type. The SDK connects to its production endpoint by default; on iOS you can point the server URL at the draft endpoint, and on the web configureChat takes an agent.draft flag — see each platform guide.
  • Your organization ID and project ID. The Agent proxy accepts only IDs, not slugs. See Find your organization and project IDs.
  • A Metabind project token (for Agent proxy mode), or an Anthropic API key (for BYOK mode). Mint project tokens server-side so they aren’t hard-coded in the binary.
  • A surface in your app to render the assistant — a screen, a sheet, a sidebar, an inline panel. The SDK ships default UI, but you can fully replace it.

​
Find your organization and project IDs

The Agent proxy returns 404 if you pass a slug instead of an ID. Studio’s page URLs and the MCP URL on Studio’s Server tab use slugs, so don’t copy the values from there. In Metabind Studio:
  1. Open your project.
  2. Click the gear icon at the top right (Project Settings).
  3. On the General page, find Project ID and Organization ID in the Config section (the SDK section in a content project). Click a value to copy it.
With the Metabind CLI, after metabind auth login:
metabind status and metabind url report the project the CLI is bound to; bind one with metabind use --project <projectId>. If the CLI has no organization selected and you belong to more than one, metabind project list returns your organizations and their IDs instead; run it again with --org <organizationId>.

​
What you don’t write

  • Tool calling logic. In Agent proxy mode the proxy runs the loop; in BYOK mode the SDK does. Either way you don’t.
  • Streaming. SSE deltas flow into the conversation state and re-render the UI.
  • Native rendering. Interactive Tool output renders through BindJS without you wiring it up.
  • Schema validation. Inputs and outputs are validated against the project’s tool schemas before they reach the renderer.

​
Token and key handling

For production, prefer the Agent proxy — your binary ships only a Metabind project token, and there is no third-party LLM key to leak.

​
Conversation state

The SDK keeps the on-screen conversation in memory. The Agent proxy keeps each conversation’s model context server-side for one hour after its last turn, keyed by a conversation ID, and has no endpoint for reading a conversation’s history. What you can restore after a relaunch or reload depends on the platform:
  • iOS: save the provider’s currentConversationId and pass it to MetabindAgentProvider(conversationId:) to resume the model’s context within that hour. The on-screen transcript is not restored; assistant.conversation.messages starts empty. See Conversation IDs.
  • Android: the SDK has no API for resuming a conversation. Each MetabindAssistant starts a new one.
  • Web: the drop-in <AgentChat /> starts a new conversation on each load. A custom UI built on useChat with MetabindAgentTransport can save its messages and restore them through the AI SDK’s id and messages options; the transport sends the chat id as the conversation ID.

​
Rendering details

When a Metabind Interactive Tool returns, its UI resource is handed to the SDK’s renderer:
  • iOS: Rendered as SwiftUI views. Embedded inside your View hierarchy.
  • Android: Rendered as Composables. Embedded inside your @Composable tree.
  • Web: Rendered in a sandboxed iframe via MCP-UI, embedded inside the <AgentChat /> React surface.
On iOS and Android, the result is a native view rendered by the platform’s UI toolkit — not a web view — so it respects your app’s typography, color scheme, and accessibility settings.

​
What ships in the SDK

  • Default chat surface — MetabindAssistantView on iOS and Android, <AgentChat /> on the web — with sender + assistant messages.
  • Rendering of Interactive Tool output — SwiftUI and Jetpack Compose via BindJS on mobile; sandboxed iframes via MCP-UI on the web.
  • The Agent proxy path on all three platforms — MetabindAgentProvider on iOS and Android, the built-in transport on the web — plus AnthropicProvider (BYOK direct) on iOS.
  • Custom LLMProvider implementations on iOS for anything else.

iOS SDK

Swift Package — install, configure, embed.

Android SDK

Maven — install, configure, embed.

Web SDK

npm — drop in AgentChat, or build on the lower-level clients.

LLM provider configuration

Agent proxy vs. BYOK; key custody.

Custom host UI

Drive your own chat surface with the lower-level API.