Skip to main content

​
useAgentMcpServers

The useAgentMcpServers hook provides the management interface for configuring the Model Context Protocol (MCP) servers actively connected to a specific agent. It facilitates retrieving the configured server list and executing connect or disconnect operations, enabling dynamic tool integration at runtime.

​
Parameters

​
agentName
string | null
The specific agent identifier used to scope the MCP server request. Providing a null value will suspend data fetching until a valid identifier is supplied.

​
Hook Interface

​
mcpServers
AgentMcpServer[]
An array detailing all MCP servers configured and available for the specified agent.
​
loading
boolean
Indicates whether the network request to retrieve the server list is currently resolving.
​
error
Error | null
Captures network failures or processing errors encountered during the server retrieval or connection process.

​
Actions

​
connect
(mcpServerId: string) => Promise<McpConnectResponse>
​
disconnect
(mcpServerId: string) => Promise<void>
​
refetch
() => Promise<void>

​
Implementation Guidelines

​
Displaying Configured Servers

To construct an administrative interface for server management, iterate over the mcpServers response: 
import { useAgentMcpServers } from "@wacht/react-router";

export function McpServerList({ agentName }: { agentName: string }) {
  const { mcpServers, loading, error } = useAgentMcpServers(agentName);

  if (loading) return <div className="text-gray-500">Retrieving configured servers...</div>;
  if (error) return <div className="text-red-500 text-sm">Retrieval failure: {error.message}</div>;
  if (mcpServers.length === 0) return <div>No custom servers configured for this agent.</div>;

  return (
    <ul className="divide-y border rounded-md">
      {mcpServers.map((server) => (
        <li key={server.id} className="p-3 flex justify-between items-center bg-white">
          <span className="font-semibold text-gray-800">{server.name}</span>
          <span className="text-xs text-gray-500 font-mono uppercase tracking-wide">
            Status: {server.status}
          </span>
        </li>
      ))}
    </ul>
  );
}

​
Managing Connection States

To implement interactive toggle controls for server connections, utilize the connect and disconnect methods in conjunction with local processing state: 
import { useState } from "react";
import { useAgentMcpServers } from "@wacht/react-router";

export function McpConnectionManager({ agentName }: { agentName: string }) {
  const { mcpServers, connect, disconnect } = useAgentMcpServers(agentName);
  const [processingId, setProcessingId] = useState<string | null>(null);

  const toggleConnection = async (server: any) => {
    setProcessingId(server.id);
    try {
      if (server.connected) {
        await disconnect(server.id);
      } else {
        await connect(server.id);
      }
    } catch (err) {
      console.error(`Status modification failed for server ${server.id}`, err);
    } finally {
      setProcessingId(null);
    }
  };

  return (
    <div className="space-y-4">
      {mcpServers.map((server) => (
        <div key={server.id} className="flex items-center justify-between p-4 border rounded-lg bg-gray-50">
          <div>
            <h4 className="font-semibold text-gray-900">{server.name}</h4>
            <p className="text-sm text-gray-500">MCP Configuration</p>
          </div>
          
          <button 
            onClick={() => toggleConnection(server)}
            disabled={processingId === server.id}
            className={`px-4 py-2 text-sm font-medium rounded-md transition-colors ${
              server.connected 
                ? 'bg-red-50 text-red-700 hover:bg-red-100 border border-red-200' 
                : 'bg-green-50 text-green-700 hover:bg-green-100 border border-green-200'
            } ${processingId === server.id ? 'opacity-50 cursor-not-allowed' : ''}`}
          >
            {processingId === server.id 
              ? "Modifying..." 
              : server.connected 
                ? "Disconnect" 
                : "Connect"}
          </button>
        </div>
      ))}
    </div>
  );
}
  • useAgentIntegrations - For managing standard third-party OAuth integrations (e.g., Slack, Notion).
  • useAgentContext - Utilized for mounting the SSE communication stream within an initiated context.