User-managed MCP servers

@assistant-ui/react-mcp is the user-facing layer for MCP. Where the server-side MCP guide wires a single fixed set of MCP servers into your API route, this package lets end users see a list of connectors, sign in via OAuth, paste a custom server URL, and have the resulting tool catalog flow into the chat — automatically.

Two ways a server reaches the user:

• Connector — a preset declared by the app developer with defineConnector(...). The user just clicks Connect (and completes auth).
• Custom server — the user supplies the URL, name, and auth in <McpAddFormPrimitive>. Hide the add UI to disable.

Both flow through one connection lifecycle, one persisted state surface, and one tool registration path.

How it works

AuiConfig({ mcp: McpManagerResource({ connectors }) })
        │
        ├─ Resource — connection lifecycle, server lookup, OAuth/bearer auth
        ├─ Auto-mounts the modelContext scope when no chat runtime provides one
        └─ Registers connected tools as frontend tools — your chat sees them automatically

The manager is a single resource. Mount it with AuiProvider like any other scope. OAuth (PKCE + RFC 7591 dynamic client registration), bearer, and "no auth" are first-class. Token refresh runs inside the MCP SDK on 401; this package mediates persistence and the redirect step.

Setup

npm install @assistant-ui/react-mcp

"use client";

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: React.ReactNode }) {
  const aui = useAui();
  const config = AuiConfig({
    mcp: McpManagerResource({
      connectors,
      connectionTimeout: 15_000,
    }),
  });
  return (
    <AuiProvider extends={aui} config={config}>
      {children}
    </AuiProvider>
  );
}

npx shadcn@latest add @assistant-ui/mcp-config

npx shadcn@latest add https://r.assistant-ui.com/base/mcp-config.json

npm install @assistant-ui/react-mcp @assistant-ui/store

npm install @base-ui/react class-variance-authority

npm install @base-ui/react

import { McpConfigDialog } from "@/components/assistant-ui/elements/mcp-config.aui";

export default function Page() {
  return (
    <header className="flex items-center justify-between">
      <h1>My app</h1>
      <McpConfigDialog />
    </header>
  );
}

<McpConfigDialog>
  <Button variant="ghost">Servers</Button>
</McpConfigDialog>

"use client";

import {
  McpManagerPrimitive,
  McpServerPrimitive,
} from "@assistant-ui/react-mcp";

const ServerCard = () => (
  <McpServerPrimitive.Root>
    <McpServerPrimitive.Icon />
    <McpServerPrimitive.Name />
    <McpServerPrimitive.Status />
    <McpServerPrimitive.ConnectButton>Connect</McpServerPrimitive.ConnectButton>
    <McpServerPrimitive.DisconnectButton>Disconnect</McpServerPrimitive.DisconnectButton>
    <McpServerPrimitive.OAuthLink>Authorize ↗</McpServerPrimitive.OAuthLink>
    <McpServerPrimitive.RemoveButton>Remove</McpServerPrimitive.RemoveButton>
    <McpServerPrimitive.Error />
  </McpServerPrimitive.Root>
);

export default function McpPage() {
  return (
    <McpManagerPrimitive.Root>
      <h2>Connectors</h2>
      <McpManagerPrimitive.Connectors>
        {() => <ServerCard />}
      </McpManagerPrimitive.Connectors>

      <h2>Your servers</h2>
      <McpManagerPrimitive.CustomServers>
        {() => <ServerCard />}
      </McpManagerPrimitive.CustomServers>

      <McpManagerPrimitive.AddCustomTrigger>
        Add custom server
      </McpManagerPrimitive.AddCustomTrigger>
    </McpManagerPrimitive.Root>
  );
}

<McpAddFormPrimitive.Root onSubmitted={() => closeDialog()}>
  <McpAddFormPrimitive.NameField />
  <McpAddFormPrimitive.UrlField />
  <McpAddFormPrimitive.AuthSelect /> {/* none | bearer | oauth */}
  <McpAddFormPrimitive.AuthFields /> {/* token or scope input depending on selection */}
  <McpAddFormPrimitive.Error />
  <McpAddFormPrimitive.Submit>Add</McpAddFormPrimitive.Submit>
  <McpAddFormPrimitive.Cancel>Cancel</McpAddFormPrimitive.Cancel>
</McpAddFormPrimitive.Root>

"use client";

import { McpOAuthCallback } from "@assistant-ui/react-mcp";
import { useRouter } from "next/navigation";
import { Providers } from "../../providers";

export default function Callback() {
  const router = useRouter();
  return (
    <Providers>
      <McpOAuthCallback onComplete={() => router.replace("/mcp")} />
    </Providers>
  );
}

"use client";
import { lastAssistantMessageIsCompleteWithToolCalls } from "ai";
import { useChatRuntime } from "@assistant-ui/ai-sdk";

export function Chat() {
  const runtime = useChatRuntime({
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
  });
  /* … */
}

// In an event handler, never in render.
const aui = useAui();
const out = await aui.mcp.server({ id: "linear" }).callTool("search", { q });

Form elicitation

Connected servers can request structured user input through form-mode elicitation. Render McpElicitationPrimitive.Items inside a server-scoped subtree, then compose fields and response actions from the unstyled primitives:

Answering a request requires composing McpElicitationPrimitive, because the server waits for the form response otherwise. Set elicitation: false on a connector or custom server to opt it out of advertising the capability. Numeric fields can stay text inputs (parseable strings are coerced); boolean fields must compose a checkbox, because string drafts for booleans are flagged invalid rather than coerced. Clearing a field returns it to the unanswered state, so an empty text input is omitted from the response rather than submitted as "" or flagged invalid, unless the schema admits "" for that property through an enum member or a "" default. Render enum properties as a select; when "" is not a member, its blank option is the unanswered state.

import { McpElicitationPrimitive } from "@assistant-ui/react-mcp";

<McpElicitationPrimitive.Items>
  {() => (
    <McpElicitationPrimitive.Root>
      <McpElicitationPrimitive.Message />
      <McpElicitationPrimitive.Error />
      <McpElicitationPrimitive.Fields>
        {({ name, schema, value, setValue }) =>
          (schema as { type?: string } | undefined)?.type === "boolean" ? (
            <label>
              {name}
              <input
                type="checkbox"
                checked={value === true}
                onChange={(event) => setValue(event.target.checked)}
              />
            </label>
          ) : (
            <input
              name={name}
              value={typeof value === "string" ? value : ""}
              onChange={(event) => setValue(event.target.value)}
            />
          )
        }
      </McpElicitationPrimitive.Fields>
      <McpElicitationPrimitive.Accept>Submit</McpElicitationPrimitive.Accept>
      <McpElicitationPrimitive.Decline>Decline</McpElicitationPrimitive.Decline>
      <McpElicitationPrimitive.Cancel>Cancel</McpElicitationPrimitive.Cancel>
    </McpElicitationPrimitive.Root>
  )}
</McpElicitationPrimitive.Items>

Client-side validation errors keep the elicitation pending so the user can correct the form, and McpElicitationPrimitive.Error renders the resulting message.

Storage

All persisted state — custom server records, OAuth tokens, callback state, PKCE verifiers, DCR client info — goes through a single MCPStorage resource. Three built-ins:

• McpLocalStorage() — default. Stores under the aui-mcp: prefix in window.localStorage.
• McpMemoryStorage() — in-process Map. Use for SSR/tests where localStorage is absent.
• McpCustomStorage({...}) — bring your own load/save. Use for app-controlled backends (e.g. POST to your API).

A storage can declare a scopeId — a stable identity for its backing data (two storages sharing a scopeId must read and write the same persisted state). Servers with bearer or oauth auth key their connection on it, so swapping to a differently-scoped storage reconnects and rebinds the OAuth provider instead of leaving a live connection writing auth state to the replaced store. Without a scopeId, a storage swap never triggers a reconnect. McpLocalStorage() derives one automatically for the shared window.localStorage (pass scopeId yourself when overriding the backing storage); McpMemoryStorage() scopes each instance uniquely; McpCustomStorage takes whatever identity its backend already has.

Only connections follow the scope. The custom server list is read from storage once when the manager mounts and is not re-read when storage changes, so a swap keeps the records loaded from the previous store and persists them into the replacement. Treat a storage as fixed for the life of the manager: when the backing identity really changes (a different signed-in user, for example), remount the manager instead of swapping its storage.

import { McpManagerResource, McpCustomStorage } from "@assistant-ui/react-mcp";

AuiConfig({
  mcp: McpManagerResource({
    connectors,
    storage: McpCustomStorage({
      scopeId: "api:/api/mcp",
      loadCustomServers: async () => fetch("/api/mcp/servers").then((r) => r.json()),
      saveCustomServers: async (records) =>
        fetch("/api/mcp/servers", { method: "PUT", body: JSON.stringify(records) }),
      loadAuthState: async (id) =>
        fetch(`/api/mcp/auth/${id}`).then((r) => (r.ok ? r.json() : null)),
      saveAuthState: async (id, state) =>
        fetch(`/api/mcp/auth/${id}`, { method: "PUT", body: JSON.stringify(state) }),
      clearAuthState: async (id) =>
        fetch(`/api/mcp/auth/${id}`, { method: "DELETE" }),
    }),
  }),
});

Auth

Three modes, declared per-connector or per-custom-record:

{ type: "none" }                                    // no auth header
{ type: "bearer", token?: "…" }                     // Authorization: Bearer …
{ type: "oauth",                                    // PKCE + DCR + refresh
  scopes?: ["read"],
  authorizationEndpoint?: "…",                      // overrides RFC 8414 discovery
  tokenEndpoint?: "…",
  registrationEndpoint?: "…",
  clientId?: "…",                                   // skip DCR with a static client
  clientSecret?: "…",
}

The OAuth provider implements the MCP SDK's OAuthClientProvider. The SDK handles discovery (RFC 8414), DCR (RFC 7591 — deprecated in favor of CIMD but still supported), PKCE, token exchange, and refresh; this package mediates MCPStorage reads/writes and the redirect step. The server id is embedded in the OAuth state parameter so a single /mcp/callback route knows which server to complete.

State & methods

Render-time state — useAuiState:

import { useAuiState } from "@assistant-ui/store";

const isHydrated = useAuiState((s) => s.mcp.isHydrated);
const connectionState = useAuiState((s) => s.mcpServer.connectionState);
//                                          ^ requires McpServerByIdProvider

Imperative methods: useAui + resolve in a callback (never during render):

const aui = useAui();

// inside an event handler:
await aui.mcp.addCustomServer({ name, url, auth: { type: "bearer", token } });
await aui.mcp.server({ id }).connect();
await aui.mcp.server({ id }).callTool("echo", { text: "hi" });

// Build a paginated resource browser/preview UI.
type ResourcePage = {
  resources: Array<{ uri: string; name?: string }>;
  nextCursor?: string;
};

const server = aui.mcp.server({ id });
const resources: ResourcePage["resources"] = [];
let nextCursor: string | undefined;

do {
  const page = (await (nextCursor === undefined
    ? server.listResources()
    : server.listResources({ cursor: nextCursor }))) as ResourcePage;
  resources.push(...page.resources);
  nextCursor = page.nextCursor;
} while (nextCursor !== undefined);

const firstResource = resources[0];
if (firstResource) {
  const preview = await server.readResource(firstResource.uri);
}

v1 scope

What ships:

• Tool listing and invocation, auto-registered as frontend tools
• Resource listing and reads for app-built browsers or preview panes
• Form-mode elicitation with app-composed fields and response actions
• OAuth (PKCE + DCR), bearer, none
• StreamableHTTP transport
• Manual connect/disconnect

What's deferred:

• Prompts, sampling
• Auto-reconnect with backoff
• Per-tool enable/disable persistence
• Per-tool consent prompts
• Out-of-the-box token encryption (use McpCustomStorage against a server endpoint)

Related