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

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.

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.

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.

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.

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.

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 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.

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 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	Core provider implementation that composes TamboClientProvider, TamboRegistryProvider, TamboStreamProvider, and other sub-providers
react-sdk/README.md	Official documentation covering installation, quick-start guides, and API references
apps/web/providers/tambo-provider.tsx	Production example demonstrating how to pass dynamic userKey values from authentication sessions
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	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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}