assistant-ui React MCP
Always consult assistant-ui.com/llms.txt for the latest API.
@assistant-ui/react-mcp lets users connect preset or custom Streamable HTTP MCP servers in the browser. The manager persists server and auth state, exposes connection state to primitives, and registers each connected tool into modelContext as a frontend tool named serverId__toolName.
References
- ./references/setup.md -- manager configuration, storage, state, imperative methods, and resource reads
- ./references/ui.md -- the copied configuration dialog and every manager, server, and add form primitive
- ./references/oauth.md -- auth shapes, OAuth callback handling, CIMD, and connection states
Mount the manager
Declare fixed connectors with defineConnector, then extend the nearest aui scope with a config. connectionTimeout is a manager default in milliseconds. A connector or custom server can override it for its own connect and listTools() readiness flow.
"use client";
import type { ReactNode } from "react";
import { AuiConfig, AuiProvider, useAui } from "@assistant-ui/react";
import { McpManagerResource, defineConnector } from "@assistant-ui/react-mcp";
const connectors = [
defineConnector({
id: "linear",
name: "Linear",
url: "https://mcp.linear.app",
auth: { type: "oauth", scopes: ["read"] },
icon: "/icons/linear.svg",
}),
defineConnector({
id: "weather",
name: "Weather",
url: "https://mcp.example.com/weather",
auth: { type: "none" },
connectionTimeout: 10_000,
}),
];
export function Providers({ children }: { children: ReactNode }) {
const aui = useAui();
const config = AuiConfig({
mcp: McpManagerResource({
connectors,
connectionTimeout: 15_000,
}),
});
return (
<AuiProvider extends={aui} config={config}>
{children}
</AuiProvider>
);
}
Connectors are application presets and cannot be removed. A custom server is user supplied through McpAddFormPrimitive or aui.mcp.addCustomServer(...). Both kinds share state, storage, elicitation, and the tool registration path. See setup for manager options and storage lifetime rules.
Continue after frontend tool calls
The manager registers connected tools automatically. A chat runtime still needs to send completed frontend tool results to the route so the model can continue.
"use client";
import type { ReactNode } from "react";
import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
export function Chat({ children }: { children: ReactNode }) {
const runtime = useChatRuntime({
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
});
return <AssistantRuntimeProvider runtime={runtime}>{children}</AssistantRuntimeProvider>;
}
If no chat runtime provides modelContext, the manager mounts a minimal one. Use aui.mcp.server({ id }).callTool(...) for a direct call in an event handler.
Use the configuration UI
Install the styled dialog with npx assistant-ui@latest add mcp-config. It is a copied runtime connected element, so import it from @/components/assistant-ui/elements/mcp-config.aui and render it under the manager provider.
import { McpConfigDialog } from "@/components/assistant-ui/elements/mcp-config.aui";
export function ServerSettings() {
return <McpConfigDialog />;
}
Pass an element as children to replace its default trigger. For a settings page, sidebar, or custom add flow, compose the headless primitives in ui.
Render elicitation requests
An MCP server can request structured input while a tool call is in flight. Render Items in the same mcpServer scope as the connected server. Set elicitation: false on a connector or custom server to opt it out of the protocol capability.
import { McpElicitationPrimitive } from "@assistant-ui/react-mcp";
type FieldSchema = {
type?: string;
enum?: readonly string[];
};
export function ElicitationRequests() {
return (
<McpElicitationPrimitive.Items>
{() => (
<McpElicitationPrimitive.Root>
<McpElicitationPrimitive.Message />
<McpElicitationPrimitive.Error />
<McpElicitationPrimitive.Fields>
{({ name, schema, value, setValue }) => {
const field = schema as FieldSchema;
if (field.type === "boolean") {
return (
<label>
{name}
<input
type="checkbox"
checked={value === true}
onChange={(event) => setValue(event.target.checked)}
/>
</label>
);
}
if (field.enum) {
return (
<label>
{name}
<select
value={typeof value === "string" ? value : ""}
onChange={(event) => setValue(event.target.value)}
>
{!field.enum.includes("") && <option value="">Select {name}</option>}
{field.enum.map((option) => (
<option key={option} value={option}>
{option}
</option>
))}
</select>
</label>
);
}
return (
<label>
{name}
<input
value={typeof value === "string" || typeof value === "number" ? String(value) : ""}
onChange={(event) => setValue(event.target.value)}
/>
</label>
);
}}
</McpElicitationPrimitive.Fields>
<McpElicitationPrimitive.Accept>Submit</McpElicitationPrimitive.Accept>
<McpElicitationPrimitive.Decline>Decline</McpElicitationPrimitive.Decline>
<McpElicitationPrimitive.Cancel>Cancel</McpElicitationPrimitive.Cancel>
</McpElicitationPrimitive.Root>
)}
</McpElicitationPrimitive.Items>
);
}
The render function receives a separate active request each time. Numeric strings are coerced when valid, while boolean fields must set a boolean. An empty string is unanswered unless the property allows it through an enum member or default, so render enum properties as a select. Accept remains disabled for missing required fields and invalid values.
v1 scope
This package ships tool listing and invocation, resource listing and reads, form elicitation, OAuth with PKCE and DCR, bearer and no auth, Streamable HTTP transport, and manual connect or disconnect. Prompts, sampling, automatic reconnect with backoff, persisted per tool enablement, per tool consent, and built in token encryption are deferred.
Common Gotchas
Tools never reach the model
- The server must be
connected. Its tools are namedserverId__toolName, not just the MCP tool name. - Configure
sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCallsonuseChatRuntimeso completed frontend tool calls resume the model.
OAuth callback fails or never completes
- The callback route must exactly match
oauthRedirectUriand renderMcpOAuthCallbackbeneath the manager provider. - A CIMD only authorization server without a registration endpoint needs a static OAuth
clientId.
Server state leaks across users or a storage swap loses records
McpLocalStorage()is browser only and stores tokens in plain text. Use an HTTP only cookie backedMcpCustomStoragefor production auth state.- Do not swap
storagefor another user. Remount the manager because custom server records hydrate only once. See storage identity.
An elicitation form stays blank
Itemsrenders nothing without pending requests and requires the matching server scope. Confirm that the server is connected and has not setelicitation: false.
A resource browser stops after the first page
- Pass each returned
nextCursortolistResources({ cursor })until it is absent, then callreadResource(uri)for a selected item.