MCPClient

import { MCPClient } from "@mcp-use/client";

MCPClient stores server configuration and returns MCPConnection instances. The root export resolves to a Node or browser implementation automatically.

Constructor

new MCPClient(config?, options?)

Param	Type	Description
`config`	`MCPClientConfigShape \| string`	Inline config or path to JSON file
`options`	`MCPClientOptions`	Code mode, global callbacks

Static methods

Method	Description
`fromDict(cfg, options?)`	Create from inline config object
`fromConfigFile(path, options?)`	Create from JSON file (Node)
`getPackageVersion()`	Installed package version string
`loadConfigFile(path)`	Read and parse a config file (Node)

Connection lifecycle

Method	Returns	Description
`connect(name)`	`Promise<MCPConnection>`	Connect and negotiate protocol (preferred)
`connectAll()`	`Promise<Record<string, MCPConnection>>`	Connect every configured server
`createSession(name, autoInit?)`	`Promise<MCPSession>`	Legacy alias for `connect`
`createAllSessions(autoInit?)`	`Promise<Record<string, MCPSession>>`	Legacy alias for `connectAll`
`getSession(name)`	`MCPSession \| null`	Get active connection or null
`requireSession(name)`	`MCPSession`	Get active connection or throw
`getAllActiveSessions()`	`Record<string, MCPSession>`	All active connections
`closeSession(name)`	`Promise<void>`	Disconnect one server
`closeAllSessions()`	`Promise<void>`	Disconnect all
`close()`	`Promise<void>`	Shutdown client (preferred on exit)

Configuration

Method	Description
`addServer(name, config)`	Add or replace a server
`removeServer(name)`	Remove config and disconnect
`getServerNames()`	List configured server names
`getServerConfig(name)`	Get one server’s config
`getConfig()`	Full client config
`saveConfig(filepath)`	Write config to JSON (Node)

Code mode (Node)

Requires options.codeMode: true or a CodeModeConfig object.

Method	Description
`executeCode(code, timeout?)`	Run JS/TS with tool access
`searchTools(query?, detailLevel?)`	Search tools across sessions

Types

MCPClientConfigShape

interface MCPClientConfigShape {
  mcpServers?: Record<string, ServerConfig>;
  clientInfo?: ClientInfo;
  onSampling?: OnSamplingCallback;
  onElicitation?: OnElicitationCallback;
  onNotification?: OnNotificationCallback;
}

Per-server configs can override callbacks. Server-level fields inherit from root when omitted.

ServerConfig (HTTP)

Field	Type	Description
`url`	`string`	MCP HTTP endpoint
`headers`	`Record<string, string>`	Request headers
`authToken`	`string`	Bearer token
`oauth`	`AutoOAuthOptions \| false`	OAuth options or disable
`authProvider`	`OAuthClientProvider`	Custom auth provider
`detectMixedAuth`	`boolean`	Discover RFC 9728 metadata after anonymous connection; defaults to `true`
`onSampling`, `onElicitation`, `onNotification`	callbacks	Per-server overrides
`roots`	`Root[]`	Initial roots
`timeout`	`number`	Connection timeout (ms)

ServerConfig (stdio, Node only)

Field	Type
`command`	`string`
`args`	`string[]`
`env`	`Record<string, string>`

MCPClientOptions

interface MCPClientOptions {
  codeMode?: boolean | CodeModeConfig;
  onSampling?: OnSamplingCallback;
  onElicitation?: OnElicitationCallback;
  onNotification?: OnNotificationCallback;
}

Other exports

Auth: createOAuthProvider, NodeOAuthClientProvider, completeOAuthFlow, isUnauthorized, FileKVStore Elicitation helpers: acceptWithDefaults, accept, decline, cancel, validate, getDefaults, applyDefaults Connectors: HttpConnector, StdioConnector, BaseConnector Types: MCPConnection, MCPSession (deprecated alias), MCPConnectionInfo, MCPAuthorizationInfo, Notification, Root, Tool Re-exports from @modelcontextprotocol/client: auth, UnauthorizedError

Overview

Server

React

Client

Agent

Constructor

Static methods

Connection lifecycle

Configuration

Code mode (Node)

Types

MCPClientConfigShape

ServerConfig (HTTP)

ServerConfig (stdio, Node only)

MCPClientOptions

Other exports

​Constructor

​Static methods

​Connection lifecycle

​Configuration

​Code mode (Node)

​Types

​MCPClientConfigShape

​ServerConfig (HTTP)

​ServerConfig (stdio, Node only)

​MCPClientOptions

​Other exports

​Related

Constructor

Static methods

Connection lifecycle

Configuration

Code mode (Node)

Types

MCPClientConfigShape

ServerConfig (HTTP)

ServerConfig (stdio, Node only)

MCPClientOptions

Other exports

Related