useMCPServer

useMCPServer registers a Model Context Protocol (MCP) server, keeps a local cache of its tool summaries, and exposes helpers to refresh or inspect the connection state. MCP servers discovered through this hook are automatically merged with frontend tools, appended to the enriched system prompt, and forwarded to createAIChatHandler.

Use it to let users opt into remote MCP servers at runtime (e.g. via a settings dialog) without redeploying your backend.

Signature

import { useMCPServer } from "ai-chat-bootstrap";
 
interface UseMCPServerOptions {
  id?: string;
  url: string;
  headers?: Record<string, string>;
  name?: string;
  autoFetchTools?: boolean;
  transportType?: "sse" | "streamable-http";
  api?: string;
}
 
interface UseMCPServerReturn {
  id: string;
  name?: string;
  isLoading: boolean;
  error: string | null;
  tools: MCPToolSummary[];
  lastLoadedAt?: number;
  refresh: () => Promise<void>;
}

Options

The hook registers the server with the internal MCP store on mount and unregisters it on unmount. Tool summaries are fetched by POSTing to the MCP bridge endpoint (use createMcpToolsHandler).

Discovery flow

1. The browser supplies the MCP descriptor (URL, headers, name) and calls your bridge endpoint (/api/mcp-discovery by default).
2. The bridge runs server-side, optionally merges additional headers (see forwardHeaders on createMcpToolsHandler), validates the MCP server, and returns the tool summaries plus any connection errors.
3. useMCPServer stores the tool list locally. If the bridge returns an errors array or a top-level error, the hook sets error so your UI can display a warning while still exposing any tools that loaded successfully.

Return value

• id, name – identifiers used throughout the UI
• isLoading, error – request state while fetching tool summaries
• tools – array of MCPToolSummary objects describing each available tool (name, description, input schema metadata)
• lastLoadedAt – timestamp of the most recent successful refresh
• refresh() – manually re-fetch tool metadata (useful for retry buttons)

Example – MCP server selector

import { ChatContainer, useMCPServer } from "ai-chat-bootstrap";
 
function MCPDemo() {
  const localServer = useMCPServer({
    url: process.env.NEXT_PUBLIC_MCP_SERVER_URL ?? "http://127.0.0.1:3030/mcp",
    name: "Local Tools",
  });
 
  return (
    <div className="space-y-4">
      <div className="flex items-center gap-2">
        <span className="text-sm text-muted-foreground">
          {localServer.isLoading
            ? "Loading MCP tools…"
            : `${localServer.tools.length} tools available`}
        </span>
        {localServer.error && (
          <button type="button" onClick={localServer.refresh}>
            Retry
          </button>
        )}
      </div>
 
      <ChatContainer
        transport={{ api: "/api/chat" }}
        mcp={{ enabled: true, api: "/api/mcp-discovery" }}
      />
    </div>
  );
}

Pair this with createAIChatHandler (set mcpEnabled: true) and a createMcpToolsHandler bridge to expose remote capability lists in the prompt and actions toolbar.

If your clients need to send per-request auth headers, keep them out of the serialized descriptor and instead provide the header names in the server handler (forwardHeaders: ["Authorization"]). The handler merges those values into the transport just before connecting.