Client-side MCP Connection

Client-side Support

Client-side MCP integration allows your application to connect to MCP servers that are accessible from the end user's browser, for instance when using a local MCP server.

This is useful for:

Local MCP servers running on the user's machine
MCP servers where the user's browser is already authenticated
Private or internal services behind a firewall, that are only visible from the user's browser

Note: There is currently no support for authenticated MCP servers when using client-side MCP connections.

Dependency note

The @tambo-ai/react/mcp subpath declares @modelcontextprotocol/sdk, zod, and zod-to-json-schema as optional peer dependencies. If you import this subpath in your application, make sure these packages are installed with compatible versions:
npm install @modelcontextprotocol/sdk@^1.24.0 zod@^4.0.0 zod-to-json-schema@^3.25.0
zod can also be ^3.25 if you prefer Zod 3; both ^3.25 and ^4.0 satisfy the SDK's zod/v3 subpath constraints. This keeps MCP support opt-in while avoiding runtime errors when you start using the MCP hooks and providers.

To implement client-side MCP support, pass mcpServers to TamboProvider:

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

function MyApp() {
  return (
    <TamboProvider
      components={...}
      mcpServers={[
        {
          // MCP server configuration
          url: "http://localhost:8123/",
          // Optional stable prefix used when multiple MCP servers are configured
          // If omitted, a key is derived from the URL hostname (e.g., "https://mcp.linear.app/mcp" -> "linear")
          serverKey: "local",
          // Optional custom headers, eg.
          // { "Authorization": `Bearer ${token}` } or { "X-Api-Key": "1234567890" }
          customHeaders: {},
          transport: MCPTransport.HTTP, // optional, defaults to HTTP
        },
      ]}
    >
      {/* Your application components */}
    </TamboProvider>
  );
}

TamboProvider automatically establishes connections to the specified MCP servers and makes their tools available to Tambo agents in your application.

Note

Tambo always prefixes names using the serverKey to identify which MCP server they come from:

Prompts: serverKey:promptName (colon separator)

Resources: serverKey:resourceUri (colon separator)

Tools: serverKey__toolName (double-underscore separator)

If you do not provide serverKey, Tambo derives one from the server URL (for example, https://mcp.linear.app/mcp becomes linear). To keep things predictable across environments, set serverKey explicitly. Avoid using : and __ in the serverKey since prompts/resources use : and tools use __ as separators; prefer letters, numbers, _, and -.

Working with MCP Resources

MCP servers can expose resources (such as files, documents, or other data) that can be referenced in prompts. Tambo provides hooks and UI components to work with these resources.

Using Resource Hooks

The useTamboMcpResourceList hook fetches all available resources from connected MCP servers:

import { useTamboMcpResourceList } from "@tambo-ai/react/mcp";

function MyComponent() {
  const { data: resources, isLoading } = useTamboMcpResourceList();

  if (isLoading) return <div>Loading resources...</div>;

  return (
    <ul>
      {resources?.map((entry) => (
        <li key={entry.resource.uri}>
          {entry.resource.name || entry.resource.uri}
        </li>
      ))}
    </ul>
  );
}

To read a specific resource, use the useTamboMcpResource hook:

import { useTamboMcpResource } from "@tambo-ai/react/mcp";

function ResourceViewer({ uri }: { uri: string }) {
  const { data: resource } = useTamboMcpResource(uri);

  if (!resource) return null;

  return (
    <div>
      {resource.contents.map((content, i) => (
        <div key={i}>{content.text || content.blob}</div>
      ))}
    </div>
  );
}

Resource Button in Message Input

The MessageInput.McpResourceButton component provides a searchable combobox for inserting resource references into messages:

import { MessageInput } from "@/components/ui/message-input";

function ChatInterface() {
  return (
    <MessageInput>
      <MessageInput.Textarea />
      <MessageInput.Toolbar>
        <MessageInput.FileButton />
        <MessageInput.McpPromptButton />
        <MessageInput.McpResourceButton />
        <MessageInput.SubmitButton />
      </MessageInput.Toolbar>
    </MessageInput>
  );
}

When a user selects a resource from the button, it inserts a reference with the syntax @<serverKey>:<resourceUri> (e.g., @linear:issue://TAM-123). The resourceUri portion (for example, issue://TAM-123) is defined by the MCP server; Tambo only adds the @<serverKey>: prefix.

Working with MCP Prompts

MCP servers can also expose prompts - pre-defined message templates that can be inserted into conversations.

Using Prompt Hooks

The useTamboMcpPromptList hook fetches all available prompts:

import { useTamboMcpPromptList } from "@tambo-ai/react/mcp";

function PromptList() {
  const { data: prompts } = useTamboMcpPromptList();

  return (
    <ul>
      {prompts?.map((entry) => (
        <li key={entry.prompt.name}>
          {entry.prompt.name}
          {entry.prompt.description && ` - ${entry.prompt.description}`}
        </li>
      ))}
    </ul>
  );
}

To fetch a specific prompt, use useTamboMcpPrompt:

import { useTamboMcpPrompt } from "@tambo-ai/react/mcp";

function PromptInserter({ promptName }: { promptName: string }) {
  const { data: prompt } = useTamboMcpPrompt(promptName, {
    // Optional arguments for the prompt
    arg1: "value1",
  });

  if (!prompt) return null;

  // Extract text from prompt messages
  const promptText = prompt.messages
    .map((msg) => (msg.content.type === "text" ? msg.content.text : ""))
    .filter(Boolean)
    .join("\n");

  return <div>{promptText}</div>;
}

Prompt Button in Message Input

The MessageInput.McpPromptButton component provides a dropdown menu for inserting prompts:

import { MessageInput } from "@/components/ui/message-input";

function ChatInterface() {
  return (
    <MessageInput>
      <MessageInput.Textarea />
      <MessageInput.Toolbar>
        <MessageInput.McpPromptButton />
        <MessageInput.SubmitButton />
      </MessageInput.Toolbar>
    </MessageInput>
  );
}

Server Namespacing

Tools, prompts, and resources are always prefixed with the serverKey to identify which MCP server they come from:

Tools: <serverKey>__<toolName> (e.g., linear__create_issue)
Prompts: <serverKey>:<promptName> (e.g., linear:new-issue)
Resources: <serverKey>:<resourceUri> (e.g., linear:issue://TAM-123)

In all cases, the serverKey portion is managed by Tambo or your configuration, while <resourceUri> is defined by the MCP server itself.

The serverKey is automatically derived from the server URL (e.g., "linear" from "https://mcp.linear.app"), or you can specify it explicitly:

<TamboProvider
  mcpServers={[
    {
      url: "https://mcp.linear.app",
      serverKey: "linear", // Optional: explicitly set the key
      transport: MCPTransport.HTTP,
    },
    {
      url: "https://api.github.com/mcp",
      serverKey: "github",
      transport: MCPTransport.HTTP,
    },
  ]}
>
  {/* Your app */}
</TamboProvider>