MCP (Model Context Protocol)

The @tambo-ai/react/mcp subpath provides hooks, a provider component, utilities, and types for integrating MCP servers into your Tambo application. All exports are imported from @tambo-ai/react/mcp.

import {
  TamboMcpProvider,
  useTamboMcpServers,
  useTamboMcpElicitation,
  useTamboMcpPromptList,
  useTamboMcpPrompt,
  useTamboMcpResourceList,
  useTamboMcpResource,
  isMcpResourceEntry,
  MCPTransport,
} from "@tambo-ai/react/mcp";

TamboMcpProvider

Provider that manages MCP server connections and tool registration. Must be placed inside TamboProvider. MCP servers are configured via the mcpServers prop on TamboProvider, not on this provider.

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

function App() {
  return (
    <TamboProvider
      apiKey="your-api-key"
      mcpServers={[
        { url: "https://mcp.example.com/sse", transport: MCPTransport.SSE },
      ]}
    >
      <TamboMcpProvider>
        <Chat />
      </TamboMcpProvider>
    </TamboProvider>
  );
}

Props

Hooks

useTamboMcpServers

Returns the list of MCP servers (connected or failed). You can call methods on the MCP client included in connected server objects.

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

function ServerStatus() {
  const servers = useTamboMcpServers();

  return (
    <ul>
      {servers.map((server) => (
        <li key={server.key}>
          {server.serverKey}: {server.client ? "Connected" : "Failed"}
        </li>
      ))}
    </ul>
  );
}

Returns: McpServer[]

useTamboMcpElicitation

Accesses the current MCP elicitation state. When an MCP server requests user input through the elicitation protocol, this hook provides the request and a function to respond.

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

function ElicitationUI() {
  const { elicitation, resolveElicitation } = useTamboMcpElicitation();

  if (!elicitation) return null;

  return (
    <div>
      <p>{elicitation.message}</p>
      <button
        onClick={() =>
          resolveElicitation?.({
            action: "accept",
            content: { confirmed: true },
          })
        }
      >
        Accept
      </button>
      <button onClick={() => resolveElicitation?.({ action: "decline" })}>
        Decline
      </button>
    </div>
  );
}

Returns:

useTamboMcpPromptList

Returns prompts from all connected MCP servers. Prompt names are prefixed with the server key (e.g., linear:create-issue).

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

function PromptPicker() {
  const { data, isPending } = useTamboMcpPromptList();

  return (
    <ul>
      {data.map((entry) => (
        <li key={entry.prompt.name}>{entry.prompt.name}</li>
      ))}
    </ul>
  );
}

Parameters:

Returns: { data: ListPromptEntry[], isPending, isError, error, refetch, ... }

useTamboMcpPrompt

Fetches a single prompt by name from the appropriate MCP server.

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

function PromptView({ promptName }: { promptName: string }) {
  const { data, isPending } = useTamboMcpPrompt(promptName, {
    projectId: "abc-123",
  });

  if (isPending) return <p>Loading...</p>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Parameters:

Returns: { data: GetPromptResult | null, isPending, isError, error, ... }

useTamboMcpResourceList

Returns resources from all connected MCP servers and the local registry. Resource URIs are prefixed with the server key or registry: for local resources.

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

function ResourceBrowser() {
  const { data, isPending } = useTamboMcpResourceList("search term");

  return (
    <ul>
      {data.map((entry) => (
        <li key={entry.resource.uri}>
          {entry.resource.name} — {entry.resource.uri}
        </li>
      ))}
    </ul>
  );
}

Parameters:

Returns: { data: ListResourceEntry[], isPending, isError, error, refetch, ... }

useTamboMcpResource

Fetches a single resource by URI. The URI must be prefixed (e.g., linear:file://foo for MCP resources, registry:file://bar for local registry resources).

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

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

  if (isPending) return <p>Loading...</p>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Parameters:

Returns: { data: ReadResourceResult | null, isPending, isError, error, ... }

useTamboElicitationContext

Deprecated. Use useTamboMcpElicitation instead.

Utilities

isMcpResourceEntry

Type guard that narrows a ListResourceEntry to an MCP-backed resource (as opposed to a local registry resource).

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

const entry: ListResourceEntry = /* ... */;

if (isMcpResourceEntry(entry)) {
  // entry.server is ConnectedMcpServer
  console.log(entry.server.serverKey);
} else {
  // entry.server is null (local registry resource)
}

MCPTransport

Enum for the transport protocol used to connect to MCP servers.

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

Types

Server Types

McpServer

Union type representing an MCP server that is either connected or failed.

type McpServer = ConnectedMcpServer | FailedMcpServer;

ConnectedMcpServer

An MCP server with an active client connection.

FailedMcpServer

An MCP server that failed to connect.

Plus the same base properties as ConnectedMcpServer (url, transport, serverKey, key, name).

McpServerInfo

Configuration object for an MCP server, passed via the mcpServers prop on TamboProvider.

Handler Types

MCPHandlers

Handlers for MCP protocol requests.

MCPElicitationHandler

type MCPElicitationHandler = (
  request: ElicitRequest,
  extra: RequestHandlerExtra,
) => Promise<ElicitResult>;

Handler invoked when an MCP server requests user input. The extra parameter includes an AbortSignal for cancellation.

MCPSamplingHandler

type MCPSamplingHandler = (
  request: CreateMessageRequest,
  extra: RequestHandlerExtra,
) => Promise<CreateMessageResult>;

Handler invoked when an MCP server requests a model response (create_message).

ProviderMCPHandlers

Provider-level handlers that receive server info as a third parameter. Applied to all servers unless overridden per-server.

Elicitation Types

TamboElicitationRequest

Elicitation request surfaced by useTamboMcpElicitation.

TamboElicitationResponse

Response to send back via resolveElicitation.

ElicitationRequestedSchema

Type alias for the schema of fields requested in an elicitation. This is an object mapping field names to PrimitiveSchemaDefinition values.

PrimitiveSchemaDefinition

Re-exported from @modelcontextprotocol/sdk. Describes a single field in an elicitation form (type, description, enum values, etc.).

List Entry Types

ListPromptEntry

A prompt from an MCP server, as returned by useTamboMcpPromptList.

ListResourceEntry

A resource from an MCP server or the local registry, as returned by useTamboMcpResourceList.

type ListResourceEntry = McpResourceEntry | RegistryResourceEntry;

When server is null, the resource is from the local registry. Use isMcpResourceEntry() to narrow.

ListPromptItem

Re-exported from @modelcontextprotocol/sdk. Contains prompt metadata: name, description, and arguments.

ListResourceItem

Re-exported from @modelcontextprotocol/sdk. Contains resource metadata: uri, name, description, and mimeType.

Metadata Types

McpServerInfo

Configuration object accepted by TamboProvider's mcpServers prop. Also exported from @tambo-ai/react/mcp.

See the McpServerInfo table above for all properties.

NormalizedMcpServerInfo

Internal type extending McpServerInfo with guaranteed transport and serverKey fields. Useful if you need to work with resolved server configurations.

Plus all properties from McpServerInfo.