Class MCPClient

Node.js-specific MCP client implementation with advanced features.

The MCPClient class provides a complete MCP client implementation for Node.js environments, extending the runtime-neutral BaseMCPClient with platform-specific capabilities:

All Connector Types: Supports Stdio, HTTP, and WebSocket connectors
Code Execution Mode: Execute code dynamically using VM or E2B sandboxes
File System Operations: Load and save configurations from/to files
Sampling & Elicitation: Handle advanced MCP protocol features
Session Management: Create and manage multiple server connections

Example

// Basic usage with config file
const client = new MCPClient('./mcp-config.json');
const session = await client.createSession('my-server');
const tools = await session.listTools();

Example

// With inline configuration
const client = new MCPClient({
  mcpServers: {
    'filesystem': {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']
    }
  }
});

Example

// With code execution mode
const client = new MCPClient('./config.json', {
  codeMode: {
    enabled: true,
    executor: 'e2b',
    executorOptions: { apiKey: process.env.E2B_API_KEY }
  }
});

const result = await client.executeCode('console.log("Hello!")');

See

MCPSession for session management

Hierarchy

BaseMCPClient
- MCPClient

Constructors

constructor

new MCPClient(
config?: string | Record<string, any>,
options?: MCPClientOptions,
): MCPClient
Creates a new MCPClient instance.

The client can be initialized with either a configuration object, a path to a configuration file, or no configuration at all (servers can be added later using addServer).
Parameters
- Optionalconfig: string | Record<string, any>
  Configuration object or path to JSON config file. If omitted, starts with empty configuration
- Optionaloptions: MCPClientOptions
  Optional client behavior configuration Options can enable code mode or provide sampling and elicitation callbacks.
Returns MCPClient
Example
```
// From config file
const client = new MCPClient('./mcp-config.json');
```
Example
```
// From inline config
const client = new MCPClient({
  mcpServers: {
    'my-server': {
      command: 'node',
      args: ['server.js']
    }
  }
});
```
Example
```
// With code mode enabled
const client = new MCPClient('./config.json', {
  codeMode: true
});
```
Example
```
// With sampling callback
const client = new MCPClient('./config.json', {
  onSampling: async (params) => {
    // Call your LLM here
    return anthropic.messages.create(params);
  }
});
```
See
- fromDict for creating from config object (alternative syntax)
- fromConfigFile for creating from file (alternative syntax)
Overrides BaseMCPClient.constructor
- Defined in core/node.ts:328

Properties

activeSessions

activeSessions: string[] = []

List of server names that have active sessions. This array is kept in sync with the sessions map and can be used to iterate over active connections.

Example

console.log(`Active servers: ${client.activeSessions.join(', ')}`);

codeMode

codeMode: boolean = false

Indicates whether code execution mode is enabled.

When true, the client provides special tools for executing code dynamically through the executeCode and searchTools methods.

Example

if (client.codeMode) {
  const result = await client.executeCode('return 2 + 2');
  console.log(result.output); // "4"
}

Methods

addServer

addServer(name: string, serverConfig: ServerConfig): void
Adds a new MCP server configuration to the client.

This method adds or updates a server configuration dynamically without needing to restart the client. The server can then be used to create new sessions.
Parameters
- name: string
  Unique name for the server
- serverConfig: ServerConfig
  Server configuration object (connector type, command, args, etc.)
Returns void
Example
```
client.addServer('new-server', {
  command: 'python',
  args: ['server.py']
});

// Now you can create a session
const session = await client.createSession('new-server');
```
See
- removeServer for removing servers
- getServerConfig for retrieving configurations
Inherited from BaseMCPClient.addServer
- Defined in core/base.ts:152

close

close(): Promise<void>
Closes the client and cleans up all resources.

This method performs a complete cleanup by:
1. Shutting down code executors (VM or E2B sandboxes)
2. Closing all active MCP sessions
3. Releasing any other held resources
Always call this method when you're done with the client to ensure proper resource cleanup, especially when using E2B sandboxes which have associated costs.
Returns Promise<void>
Example
```
const client = new MCPClient('./config.json', { codeMode: true });
await client.createAllSessions();

// Do work...

// Clean up
await client.close();
```
Example
```
// Use in shutdown handler
process.on('SIGINT', async () => {
  console.log('Shutting down...');
  await client.close();
  process.exit(0);
});
```
See
closeAllSessions for closing just the sessions
Overrides BaseMCPClient.close
- Defined in core/node.ts:761

closeAllSessions

closeAllSessions(): Promise<void>
Closes all active sessions and cleans up their resources.

This method iterates through all sessions and attempts to close each one gracefully. If any session fails to close, the error is logged but the method continues to close remaining sessions.

This is particularly useful for cleanup on application shutdown.

Returns Promise<void>
Example
```
// Clean shutdown
try {
  await client.closeAllSessions();
  console.log('All sessions closed successfully');
} catch (error) {
  console.error('Error during cleanup:', error);
}
```
Example
```
// Use in application shutdown handler
process.on('SIGINT', async () => {
  console.log('Shutting down...');
  await client.closeAllSessions();
  process.exit(0);
});
```
See
- closeSession for closing individual sessions
- createAllSessions for creating sessions
Inherited from BaseMCPClient.closeAllSessions
- Defined in core/base.ts:625

closeSession

closeSession(serverName: string): Promise<void>
Closes a session and cleans up its resources.

This method gracefully disconnects from the server and removes the session from the active sessions list. It's safe to call even if the session doesn't exist.
Parameters
- serverName: string
  Name of the server whose session should be closed
Returns Promise<void>
Example
```
// Close a specific session
await client.closeSession('my-server');

// Verify it's closed
console.log(client.activeSessions.includes('my-server')); // false
```
See
- closeAllSessions for closing all sessions at once
- createSession for creating new sessions
Inherited from BaseMCPClient.closeSession
- Defined in core/base.ts:564

connect

connect(serverName: string): Promise<MCPConnection>
Connect to a configured MCP server and return a ready, protocol-neutral connection.

The returned connection represents either a legacy sessionful server or a modern sessionless server uniformly. Inspect MCPConnection.info for the negotiated protocol version and normalized server metadata.
Parameters
- serverName: string
  The configured server name.
Returns Promise<MCPConnection>
Inherited from BaseMCPClient.connect
- Defined in core/base.ts:397

connectAll

connectAll(): Promise<Record<string, MCPConnection>>
Connect to every configured server sequentially.

Each result uses the same MCPConnection API regardless of whether the negotiated protocol is legacy/sessionful or modern/sessionless.

Returns Promise<Record<string, MCPConnection>>
Inherited from BaseMCPClient.connectAll
- Defined in core/base.ts:449

createAllSessions

createAllSessions(
autoInitialize?: boolean,
): Promise<Record<string, MCPConnection>>
Creates sessions for all configured MCP servers.

This is a convenience method that iterates through all servers in the configuration and creates a session for each one. Sessions are created sequentially to avoid overwhelming the system.
Parameters
- autoInitialize: boolean = true
  Whether to automatically initialize each session (default: true)
Returns Promise<Record<string, MCPConnection>>
A promise that resolves to a map of server names to sessions
Example
```
// Create sessions for all configured servers
const sessions = await client.createAllSessions();
console.log(`Created ${Object.keys(sessions).length} sessions`);

// List tools from all servers
for (const [name, session] of Object.entries(sessions)) {
  const tools = await session.listTools();
  console.log(`${name}: ${tools.length} tools`);
}
```
See
- createSession for creating individual sessions
- closeAllSessions for closing all sessions
Inherited from BaseMCPClient.createAllSessions
- Defined in core/base.ts:427

createSession

createSession(
serverName: string,
autoInitialize?: boolean,
): Promise<MCPConnection>
Creates a new session for connecting to an MCP server.
Parameters
- serverName: string
  The name of the server as defined in the client configuration
- autoInitialize: boolean = true
  Whether to automatically initialize the session (default: true)
Returns Promise<MCPConnection>
A promise that resolves to the created MCPSession instance
Deprecated
Use connect; modern MCP servers are sessionless.

This method initializes a connection to the specified server using the configuration provided during client construction. Sessions manage the lifecycle of connections and provide methods for calling tools, listing resources, and more.

If a session already exists for the server, it will be replaced with a new one.

Throws
If the server is not found in the configuration
Example
```
// Create and initialize a session
const session = await client.createSession('my-server');
const tools = await session.listTools();

// Create without auto-initialization
const session = await client.createSession('my-server', false);
await session.connect();
await session.initialize();
```
See
- MCPSession for session management methods
- closeSession for closing sessions
- getSession for retrieving existing sessions
Inherited from BaseMCPClient.createSession
- Defined in core/base.ts:304

executeCode

executeCode(code: string, timeout?: number): Promise<ExecutionResult>
Executes JavaScript/TypeScript code in a sandboxed environment.

This method is only available when code mode is enabled. It executes the provided code in an isolated environment (VM or E2B sandbox) and returns the results including stdout, stderr, and return value.
Parameters
- code: string
  JavaScript/TypeScript code to execute
- Optionaltimeout: number
  Optional execution timeout in milliseconds
Returns Promise<ExecutionResult>
Execution result with output, errors, and return value
Throws
If code mode is not enabled
Example
```
const client = new MCPClient('./config.json', { codeMode: true });

const result = await client.executeCode(`
  console.log('Hello, world!');
  return 2 + 2;
`);

console.log(result.stdout);      // "Hello, world!\n"
console.log(result.returnValue); // 4
```
Example
```
// With timeout
try {
  const result = await client.executeCode('while(true) {}', 1000);
} catch (error) {
  console.log('Execution timed out');
}
```
See
searchTools for discovering available tools in code mode
- Defined in core/node.ts:644

getAllActiveSessions

getAllActiveSessions(): Record<string, MCPConnection>
Gets all active sessions as a map of server names to sessions.

Returns Record<string, MCPConnection>
Map of server names to their active sessions
Example
```
const sessions = client.getAllActiveSessions();

// Iterate over all active sessions
for (const [name, session] of Object.entries(sessions)) {
  console.log(`Server: ${name}`);
  const tools = await session.listTools();
  console.log(`  Tools: ${tools.length}`);
}
```
See
- activeSessions for just the list of server names
- getSession for retrieving individual sessions
Inherited from BaseMCPClient.getAllActiveSessions
- Defined in core/base.ts:537

getConfig

getConfig(): MCPClientConfigShape
Gets the complete client configuration.

Returns MCPClientConfigShape
Complete configuration object including all server definitions
Example
```
const config = client.getConfig();
console.log(`Total servers: ${Object.keys(config.mcpServers).length}`);
```
See
getServerConfig for retrieving individual server configurations
Inherited from BaseMCPClient.getConfig
- Defined in core/base.ts:243

getServerConfig

getServerConfig(name: string): ServerConfig | undefined
Gets the configuration for a specific MCP server.
Parameters
- name: string
  Name of the server
Returns ServerConfig | undefined
Server configuration object, or undefined if not found
Example
```
const config = client.getServerConfig('my-server');
if (config) {
  console.log(`Command: ${config.command}`);
  console.log(`Args: ${config.args.join(' ')}`);
}
```
See
getConfig for retrieving the entire configuration
Inherited from BaseMCPClient.getServerConfig
- Defined in core/base.ts:226

getServerNames

getServerNames(): string[]
Gets the names of all configured MCP servers (excluding internal servers).

This method overrides the base implementation to filter out internal meta-servers like the code mode server, which is an implementation detail not intended for direct user interaction.

Returns string[]
Array of user-configured server names
Example
```
const names = client.getServerNames();
console.log(`User servers: ${names.join(', ')}`);
// Note: 'code_mode' is excluded even if code mode is enabled
```
See
activeSessions for servers with active sessions
Overrides BaseMCPClient.getServerNames
- Defined in core/node.ts:719

getSession

getSession(serverName: string): MCPConnection | null
Retrieves an existing session by server name.

This method returns null if no session exists, making it safe for checking session existence without throwing errors.
Parameters
- serverName: string
  Name of the server
Returns MCPConnection | null
The session instance or null if not found
Example
```
const session = client.getSession('my-server');
if (session) {
  const tools = await session.listTools();
} else {
  console.log('Session not found, creating...');
  await client.createSession('my-server');
}
```
See
- requireSession for getting a session that throws if not found
- createSession for creating sessions
Inherited from BaseMCPClient.getSession
- Defined in core/base.ts:476

removeServer

removeServer(name: string): Promise<void>
Removes an MCP server configuration from the client.

This method removes a server configuration and cleans up any active sessions associated with that server. If there's an active session, it will be removed from the active sessions list.
Parameters
- name: string
  Name of the server to remove
Returns Promise<void>
Example
```
// Remove a server configuration
await client.removeServer('old-server');

// The server name will no longer appear in getServerNames()
console.log(client.getServerNames()); // 'old-server' is gone
```
See
- addServer for adding servers
- closeSession for properly closing sessions before removal
Inherited from BaseMCPClient.removeServer
- Defined in core/base.ts:179

requireSession

requireSession(serverName: string): MCPConnection
Retrieves an existing session by server name, throwing if not found.

This method is useful when you need to ensure a session exists before proceeding. It throws a descriptive error if the session is not found.
Parameters
- serverName: string
  Name of the server
Returns MCPConnection
The session instance
Throws
If the session is not found
Example
```
try {
  const session = client.requireSession('my-server');
  const tools = await session.listTools();
} catch (error) {
  console.error('Session not found:', error.message);
}
```
See
- getSession for a null-returning alternative
- createSession for creating sessions
Inherited from BaseMCPClient.requireSession
- Defined in core/base.ts:507

saveConfig

saveConfig(filepath: string): void
Saves the current configuration to a file.

This Node.js-specific method writes the client's current configuration (including all server definitions) to a JSON file. The directory will be created if it doesn't exist.
Parameters
- filepath: string
  Path where the configuration file should be saved
Returns void
Example
```
const client = new MCPClient();
client.addServer('my-server', {
  command: 'node',
  args: ['server.js']
});

// Save configuration for later use
client.saveConfig('./mcp-config.json');
```
See
fromConfigFile for loading configurations
- Defined in core/node.ts:468

searchTools

searchTools(
query?: string,
detailLevel?: "names" | "descriptions" | "full",
): Promise<ToolSearchResponse>
Searches for available tools across all MCP servers.

This method is only available when code mode is enabled. It searches through tools from all active servers and returns matching tools based on the query and detail level.
Parameters
- query: string = ""
  Optional search query to filter tools (defaults to empty string for all tools)
- detailLevel: "names" | "descriptions" | "full" = "full"
  Level of detail to return: "names", "descriptions", or "full"
Returns Promise<ToolSearchResponse>
Tool search results with matching tools
Throws
If code mode is not enabled
Example
```
const client = new MCPClient('./config.json', { codeMode: true });
await client.createAllSessions();

// Search for all tools
const allTools = await client.searchTools();
console.log(`Found ${allTools.tools.length} tools`);

// Search for specific tools
const fileTools = await client.searchTools('file', 'descriptions');
```
See
executeCode for executing code in code mode
- Defined in core/node.ts:688

`Static`fromConfigFile

fromConfigFile(path: string, options?: MCPClientOptions): MCPClient
Creates a client instance from a configuration file.

This static factory method loads MCP server configurations from a JSON file and creates a new client instance.
Parameters
- path: string
  Path to the JSON configuration file
- Optionaloptions: MCPClientOptions
  Optional client behavior configuration
Returns MCPClient
New MCPClient instance
Throws
If the file cannot be read or parsed
Example
```
const client = MCPClient.fromConfigFile('./mcp-config.json');
await client.createAllSessions();
```
Example
```
// With code mode
const client = MCPClient.fromConfigFile('./config.json', {
  codeMode: true
});
```
See
- MCPClient for direct instantiation
- fromDict for inline configuration
- Defined in core/node.ts:438

`Static`fromDict

fromDict(cfg: Record<string, any>, options?: MCPClientOptions): MCPClient
Creates a client instance from a configuration dictionary.

This static factory method provides an alternative syntax for creating a client from an inline configuration object.
Parameters
- cfg: Record<string, any>
  Configuration dictionary with server definitions
- Optionaloptions: MCPClientOptions
  Optional client behavior configuration
Returns MCPClient
New MCPClient instance
Example
```
const client = MCPClient.fromDict({
  mcpServers: {
    'filesystem': {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']
    }
  }
});
```
See
- MCPClient for direct instantiation
- fromConfigFile for loading from file
Overrides BaseMCPClient.fromDict
- Defined in core/node.ts:403

`Static`getPackageVersion

getPackageVersion(): string
Gets the mcp-use package version.

This static method returns the version string of the installed mcp-use package, which is useful for debugging and compatibility checks.

Returns string
The package version string (e.g., "1.13.2")
Example
```
console.log(`mcp-use version: ${MCPClient.getPackageVersion()}`);
```
- Defined in core/node.ts:247

Class MCPClient

Example

Example

Example

See

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns MCPClient

Example

Example

Example

Example

See

Properties

activeSessions

Example

codeMode

Example

Methods

addServer

Parameters

Returns void

Example

See

close

Returns Promise<void>

Example

Example

See

closeAllSessions

Returns Promise<void>

Example

Example

See

closeSession

Parameters

Returns Promise<void>

Example

See

connect

Parameters

Returns Promise<MCPConnection>

connectAll

Returns Promise<Record<string, MCPConnection>>

createAllSessions

Parameters

Returns Promise<Record<string, MCPConnection>>

Example

See

createSession

Parameters

Returns Promise<MCPConnection>

Deprecated

Throws

Example

See

executeCode

Parameters

Returns Promise<ExecutionResult>

Throws

Example

Example

See

getAllActiveSessions

Returns Record<string, MCPConnection>

Example

See

getConfig

Returns MCPClientConfigShape

Example

See

getServerConfig

Parameters

Returns ServerConfig | undefined

`Static`fromConfigFile

`Static`fromDict

`Static`getPackageVersion