> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Embed an assistant in your app
> Embed a governed agent that calls your Metabind tools and renders them as SwiftUI, Jetpack Compose, or React inside your iOS, Android, or web app
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.
.png)
## What the SDK gives you
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
| Platform | Package | Renderer |
| - | - | - |
| iOS | `MetabindAI` — a product of the [`metabind-apple`](https://github.com/metabindai/metabind-apple) Swift Package | SwiftUI via `bindjs-apple` |
| Android | `ai.metabind:metabindai-android` — a Maven artifact from [`metabind-android`](https://github.com/metabindai/metabind-android) | Jetpack Compose via `bindjs-android` |
| Web | [`@metabindai/agent-ui`](https://github.com/metabindai/metabind-web) — an npm package from `metabind-web` | React; Interactive Tools render in a sandboxed iframe via MCP-UI |
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 `` React component. For working references, see the [iOS assistant demo](https://github.com/metabindai/metabind-apple/tree/main/Samples/MetabindAI/AssistantDemo), the [Android assistant demo](https://github.com/metabindai/metabind-android/tree/main/samples/assistant-demo), and the [web example app](https://github.com/metabindai/metabind-web/tree/main/examples/example-metabind-react-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, `` 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](/guides/assistant-sdk/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](#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`:
```bash theme={null}
metabind project list # each project's "id" and "organizationId"
metabind status # the bound project's "orgId" and "projectId", under "context"
metabind url -q # the bound project's MCP URL: https://mcp.metabind.ai//projects/
```
`metabind status` and `metabind url` report the project the CLI is bound to; bind one with `metabind use --project `. 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 `.
## 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
| What | Where it lives |
| - | - |
| Metabind project token | Mint per user / session on your backend. The SDK holds it for the session and uses it to authenticate to the MCP server and (in proxy mode) to the Agent proxy. |
| LLM provider API key (Agent proxy mode) | Server-side only. Your client never sees it. |
| LLM provider API key (BYOK direct mode) | Delivered to the SDK by your auth flow; ideally short-lived. Don't hard-code in production. |
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](/guides/assistant-sdk/llm-provider-configuration#conversation-ids).
* **Android:** the SDK has no API for resuming a conversation. Each `MetabindAssistant` starts a new one.
* **Web:** the drop-in `` 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 `` 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, `` 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.
## Related
Swift Package — install, configure, embed.
Maven — install, configure, embed.
npm — drop in AgentChat, or build on the lower-level clients.
Agent proxy vs. BYOK; key custody.
Drive your own chat surface with the lower-level API.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.