useActorMcpServers() hook
useActorMcpServers() is the MCP server management hook for the agents surface. It lists the deployment MCP servers available to the current actor and exposes the two connection actions that open or revoke a user connection.Usage
The following example shows a basic usage of useActorMcpServers().
import { useActorMcpServers } from '@wacht/nextjs';export default function McpServers() { const { servers, connect, disconnect } = useActorMcpServers(true); return ( <ul> {servers.map((server) => ( <li key={server.id}> {server.name} <button onClick={async () => { const result = await connect(server.id); window.open(result.data.auth_url, '_blank', 'noopener,noreferrer'); }} > Connect </button> <button onClick={() => void disconnect(server.id)}>Disconnect</button> </li> ))} </ul> );}Return value
The hook returns the following fields and methods.
›servers?: ActorMcpServerSummary[] | undefined;
servers?: ActorMcpServerSummary[] | undefined;Current MCP servers available to the actor.
›id?: string | undefined;
id?: string | undefined;MCP server identifier.
›name?: string | undefined;
name?: string | undefined;Display name.
›endpoint?: string | undefined;
endpoint?: string | undefined;Configured server endpoint.
›auth_type?: string | undefined;
auth_type?: string | undefined;Authentication strategy for the server.
›requires_user_connection?: boolean | undefined;
requires_user_connection?: boolean | undefined;Whether the current actor must connect the server before it can be used.
›connection_status?: "ready" | "connected" | "not_connected" | "expired" | undefined;
connection_status?: "ready" | "connected" | "not_connected" | "expired" | undefined;Current user connection status.
›connected_at?: string | undefined | undefined;
connected_at?: string | undefined | undefined;Connection timestamp when the user has connected the server.
›expires_at?: string | undefined | undefined;
expires_at?: string | undefined | undefined;Expiry timestamp for an expiring connection.
›connect?: (mcpServerId: string) => Promise<ApiResult<{ auth_url: string }>> | undefined;
connect?: (mcpServerId: string) => Promise<ApiResult<{ auth_url: string }>> | undefined;Starts the user connection flow and returns the authorization URL on `result.data.auth_url`.
›disconnect?: (mcpServerId: string) => Promise<ApiResult<{ success: boolean }>> | undefined;
disconnect?: (mcpServerId: string) => Promise<ApiResult<{ success: boolean }>> | undefined;Disconnects the current actor from the server and returns the success payload on `result.data`.
Overview
The read side of this hook is a simple MCP server list. The write side keeps the response envelope because the caller needs the returned
auth_url on connect and the explicit success payload on disconnect.When to use it
Use
useActorMcpServers() when your agents workspace exposes user-facing MCP integrations. It fits an integrations page, an MCP settings panel, or any UI that needs to start a per-user connection flow for a deployment-level MCP server.