# How to Set Up Tambo AI for a React Project: Complete Integration Guide

> Learn how to set up Tambo AI for your React project. Integrate generative UI effortlessly using Zod schemas and custom hooks. Get started with our complete guide.

- Repository: [tambo ai/tambo](https://github.com/tambo-ai/tambo)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Wrap your React application with `TamboProvider` from `@tambo-ai/react`, register your UI components with Zod schemas, and use the `useTambo` and `useTamboThreadInput` hooks to enable LLM-driven generative UI.**

Tambo AI is a React-first SDK that transforms standard UI components into generative interfaces that large language models can render, stream props to, and manage statefully. This guide walks you through how to set up Tambo AI for a React project using the `tambo-ai/tambo` repository, covering installation, component registration, provider configuration, and hook integration.

## Step 1: Install the Tambo AI React SDK

Install the core React SDK and the recommended Zod version for schema validation. The Tambo AI documentation recommends Zod 4 for new projects, though Zod 3 remains compatible.

```bash
npm install @tambo-ai/react
npm install zod@^4 zod-to-json-schema@^3.25.1

```

The `zod-to-json-schema` package converts your Zod schemas into JSON Schema definitions that the LLM can understand and use for tool calling.

## Step 2: Register UI Components with Zod Schemas

Create an array of component descriptors that tell Tambo AI which React components are available for generative rendering. Each descriptor requires a `name`, `description`, `component` reference, and a `propsSchema` defined with Zod.

```tsx
import { z } from "zod";
import { Graph } from "./components/Graph";

const components = [
  {
    name: "Graph",
    description: "Displays data as interactive charts (line, bar, or pie)",
    component: Graph,
    propsSchema: z.object({
      data: z.array(
        z.object({ 
          name: z.string(), 
          value: z.number() 
        })
      ),
      type: z.enum(["line", "bar", "pie"]),
    }),
  },
];

```

The `propsSchema` enables the LLM to understand what data structure the component expects, allowing it to generate valid props dynamically.

## Step 3: Register Client-Side Tools (Optional)

If your application requires the AI to execute browser-side functions—such as fetching weather data or querying a local database—register them as tools with input and output schemas.

```tsx
import { z } from "zod";

const tools = [
  {
    name: "getWeather",
    description: "Fetches current weather conditions for a specified location",
    tool: async ({ location }: { location: string }) => {
      const res = await fetch(
        `/api/weather?q=${encodeURIComponent(location)}`
      );
      return res.json();
    },
    inputSchema: z.object({ location: z.string() }),
    outputSchema: z.object({
      temperature: z.number(),
      condition: z.string(),
      location: z.string(),
    }),
  },
];

```

These tools execute in the browser and can access client-side APIs, unlike server-side functions.

## Step 4: Configure TamboProvider

Wrap your application root (or a specific subtree) with `TamboProvider` to inject the Tambo AI context. The provider composes multiple internal providers—including `TamboClientProvider`, `TamboRegistryProvider`, and `TamboStreamProvider`—as implemented in [`react-sdk/src/v1/providers/tambo-v1-provider.tsx`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/v1/providers/tambo-v1-provider.tsx).

```tsx
import { TamboProvider } from "@tambo-ai/react";

function App() {
  return (
    <TamboProvider
      apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY!}
      userKey={currentUserId}
      components={components}
      tools={tools}
    >
      <ChatInterface />
    </TamboProvider>
  );
}

```

**Critical configuration notes:**

- **`apiKey`**: Your Tambo AI API key from the dashboard.
- **`userKey`**: Required for thread scoping and persistence. Pass a stable user identifier (or OAuth token) to ensure conversation continuity.
- **`components`**: The array of registered UI components from Step 2.
- **`tools`**: Optional array of client-side tools from Step 3.

## Step 5: Implement Chat Interface with Hooks

Consume the Tambo AI state and actions using the `useTambo` and `useTamboThreadInput` hooks. The `useTambo` hook exposes messages, streaming status, and thread management, while `useTamboThreadInput` handles input state and message submission.

```tsx
import { useTambo, useTamboThreadInput } from "@tambo-ai/react";

function ChatInterface() {
  const { messages, isStreaming } = useTambo();
  const { value, setValue, submit, isPending } = useTamboThreadInput();

  return (
    <form
      onSubmit={async (e) => {
        e.preventDefault();
        await submit();
      }}
    >
      <div className="messages">
        {messages.map((msg) => (
          <Message key={msg.id} message={msg} />
        ))}
        {isStreaming && <LoadingIndicator />}
      </div>
      <input
        value={value}
        onChange={(e) => setValue(e.target.value)}
        placeholder="Ask anything..."
      />
      <button type="submit" disabled={isPending}>
        Send
      </button>
    </form>
  );
}

```

For a complete implementation example, reference the full-stack demo in [`showcase/src/app/template.tsx`](https://github.com/tambo-ai/tambo/blob/main/showcase/src/app/template.tsx) within the Tambo repository.

## Step 6: Integrate MCP Servers (Optional)

To extend Tambo AI with external tools via the Model Context Protocol (MCP), pass an `mcpServers` array to `TamboProvider`. This enables the LLM to invoke tools hosted on MCP servers over HTTP or STDIO transports.

```tsx
import { MCPTransport } from "@tambo-ai/react/mcp";

const mcpServers = [
  {
    name: "filesystem",
    url: "http://localhost:8261/mcp",
    transport: MCPTransport.HTTP,
  },
];

<TamboProvider
  apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY!}
  userKey={currentUserId}
  components={components}
  mcpServers={mcpServers}
>
  <App />
</TamboProvider>;

```

For UI components that manage MCP configuration, see [`packages/ui-registry/src/components/message-input/mcp-config-modal.tsx`](https://github.com/tambo-ai/tambo/blob/main/packages/ui-registry/src/components/message-input/mcp-config-modal.tsx) in the source repository.

## Key Source Files in the Tambo Repository

Understanding the internal architecture helps with debugging and advanced customization:

| File | Purpose |
|------|---------|
| [`react-sdk/src/v1/providers/tambo-v1-provider.tsx`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/v1/providers/tambo-v1-provider.tsx) | Core provider implementation that composes `TamboClientProvider`, `TamboRegistryProvider`, `TamboStreamProvider`, and other sub-providers |
| [`react-sdk/README.md`](https://github.com/tambo-ai/tambo/blob/main/react-sdk/README.md) | Official documentation covering installation, quick-start guides, and API references |
| [`apps/web/providers/tambo-provider.tsx`](https://github.com/tambo-ai/tambo/blob/main/apps/web/providers/tambo-provider.tsx) | Production example demonstrating how to pass dynamic `userKey` values from authentication sessions |
| [`showcase/src/app/template.tsx`](https://github.com/tambo-ai/tambo/blob/main/showcase/src/app/template.tsx) | Full-stack implementation reference showing chat UI integration patterns |
| [`packages/ui-registry/src/components/message-input/mcp-config-modal.tsx`](https://github.com/tambo-ai/tambo/blob/main/packages/ui-registry/src/components/message-input/mcp-config-modal.tsx) | Reference implementation for MCP server configuration UI components |

## Summary

- **Install** the SDK with `npm install @tambo-ai/react` and Zod 4 for schema validation.
- **Register components** by creating descriptors with `name`, `description`, `component`, and `propsSchema` to enable LLM-driven rendering.
- **Configure the provider** by wrapping your app with `TamboProvider`, passing `apiKey`, `userKey`, and your component registry.
- **Implement the UI** using `useTambo` for message state and `useTamboThreadInput` for input handling and submission.
- **Extend functionality** by adding client-side tools or MCP server integrations for external capabilities.

## Frequently Asked Questions

### Do I need to use Zod 4, or does Zod 3 work with Tambo AI?

Zod 3 remains compatible with Tambo AI, but the official documentation recommends Zod 4 for new projects to ensure optimal schema validation performance and compatibility with the latest `zod-to-json-schema` converter. Both versions support the `propsSchema` and `inputSchema` definitions required for component and tool registration.

### What is the purpose of the userKey prop in TamboProvider?

The `userKey` prop is required for thread scoping and persistence. It ensures that conversation threads are isolated per user and maintained across sessions. Pass a stable user identifier from your authentication system (such as a user ID or OAuth token) to enable the AI to maintain context and history specific to that individual user.

### Can I use Tambo AI with Next.js App Router?

Yes, Tambo AI works with Next.js App Router. Install the SDK in your Next.js project and wrap your root layout or specific page components with `TamboProvider`. Ensure you prefix environment variables containing the API key with `NEXT_PUBLIC_` (e.g., `NEXT_PUBLIC_TAMBO_API_KEY`) so they are available in the browser bundle where the React SDK operates.

### How do I add external tools via MCP servers?

Pass an `mcpServers` array to `TamboProvider` containing server descriptors with `name`, `url`, and `transport` properties. Import `MCPTransport` from `@tambo-ai/react/mcp` to specify HTTP or STDIO transports. The LLM will then be able to invoke tools hosted on these MCP servers during conversations, extending capabilities beyond the browser environment.