Skip to main content
View the client source on GitHub: https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/client.ts
View the executor base types: https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/client/executors/base.ts
View the Code Mode connector: https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/client/connectors/codeMode.ts
Code Mode adds code execution to MCPClient. When enabled, the client exposes executeCode() and searchTools(), and the internal Code Mode connector provides execute_code and search_tools tools for agents. Import the client and public executor types from mcp-use: 
import { BaseCodeExecutor, MCPClient } from "mcp-use";
import type {
  CodeModeConfig,
  E2BExecutorOptions,
  ExecutionResult,
  VMExecutorOptions,
} from "mcp-use";

​
Enable Code Mode

Set codeMode: true to use the default VM executor. Pass CodeModeConfig when you need E2B, a custom executor function, a custom executor class, or executor options. Signature 
interface MCPClientOptions {
  codeMode?: boolean | CodeModeConfig;
}

​
CodeModeConfig

Advanced configuration for code execution mode. Fields
​
enabled
boolean
Whether code execution mode is enabled.
​
executor
"vm" | "e2b" | CodeExecutorFunction | BaseCodeExecutor
Executor implementation. Defaults to "vm".
​
executorOptions
VMExecutorOptions | E2BExecutorOptions
Executor-specific options.
Signature 
interface CodeModeConfig {
  enabled: boolean;
  executor?: "vm" | "e2b" | CodeExecutorFunction | BaseCodeExecutor;
  executorOptions?: VMExecutorOptions | E2BExecutorOptions;
}

​
Executor options

​
VMExecutorOptions

Options for the Node.js VM executor. Fields
​
timeoutMs
number
Maximum execution time in milliseconds. Defaults to 30000.
​
memoryLimitMb
number
Optional memory limit in megabytes. When omitted, no memory limit is configured.
Signature 
interface VMExecutorOptions {
  timeoutMs?: number;
  memoryLimitMb?: number;
}

​
E2BExecutorOptions

Options for the E2B cloud sandbox executor. Fields
​
apiKey
string
E2B API key. Required.
​
timeoutMs
number
Maximum execution time in milliseconds. Defaults to 300000.
Signature 
interface E2BExecutorOptions {
  apiKey: string;
  timeoutMs?: number;
}

​
MCPClient methods

​
executeCode

Executes JavaScript or TypeScript code with access to connected MCP tools. Code Mode must be enabled. Parameters
​
code
string
required
Code to execute.
​
timeout
number | undefined
default:"undefined"
Per-execution timeout in milliseconds.
Returns
​
returns
Promise<ExecutionResult>
Throws Throws Error when Code Mode is not enabled. Signature 
executeCode(code: string, timeout?: number): Promise<ExecutionResult>

​
searchTools

Searches tools across active MCP sessions. Code Mode must be enabled. Parameters
​
query
string
default:"\"\""
Search query. Empty string returns all tools.
​
detailLevel
"names" | "descriptions" | "full"
default:"\"full\""
Amount of detail to return for each matching tool.
Returns
​
returns
Promise<ToolSearchResponse>
Throws Throws Error when Code Mode is not enabled. Signature 
searchTools(
  query?: string,
  detailLevel?: "names" | "descriptions" | "full"
): Promise<ToolSearchResponse>

​
close

Closes the client. When Code Mode has created an executor, close() cleans up executor resources before closing sessions. Returns
​
returns
Promise<void>
Signature 
close(): Promise<void>

​
ExecutionResult

Result returned by executeCode(). Fields
​
result
unknown
Return value from the executed code.
​
logs
string[]
Console output captured during execution.
​
error
string | null
Error message when execution failed, otherwise null.
​
execution_time
number
Execution duration in seconds.
Signature 
interface ExecutionResult {
  result: unknown;
  logs: string[];
  error: string | null;
  execution_time: number;
}

​
Tool search types

​
ToolSearchResponse

Response returned by searchTools() and by the runtime search_tools() helper available inside executed code. Fields
​
meta
ToolSearchMeta
Search metadata, including total tool count and namespaces.
​
results
ToolSearchResult[]
Matching tools.
Signature 
interface ToolSearchResponse {
  meta: ToolSearchMeta;
  results: ToolSearchResult[];
}

​
ToolSearchMeta

Fields
​
total_tools
number
Total number of tools across active sessions before filtering.
​
namespaces
string[]
Sorted server namespaces that have tools.
​
result_count
number
Number of matching tools returned in results.
Signature 
interface ToolSearchMeta {
  total_tools: number;
  namespaces: string[];
  result_count: number;
}

​
ToolSearchResult

Fields
​
name
string
Tool name.
​
server
string
Server namespace.
​
description
string
Tool description. Included when detailLevel is "descriptions" or "full".
​
input_schema
Tool['inputSchema']
Tool input schema. Included when detailLevel is "full".
Signature 
interface ToolSearchResult {
  name: string;
  server: string;
  description?: string;
  input_schema?: Tool["inputSchema"];
}

​
Custom executors

​
CodeExecutorFunction

Function form for a custom executor. Signature 
type CodeExecutorFunction = (
  code: string,
  timeout?: number
) => Promise<ExecutionResult>

​
BaseCodeExecutor

Extend BaseCodeExecutor when a custom executor needs access to MCP sessions, namespaces, and the shared tool search function. Constructor parameters
​
client
MCPClient
required
Client whose configured servers should be exposed to executed code.
Methods
​
execute
(code: string, timeout?: number) => Promise<ExecutionResult>
Runs code. Subclasses must implement this method.
​
cleanup
() => Promise<void>
Releases executor resources. Subclasses must implement this method.
​
createSearchToolsFunction
() => SearchToolsFunction
Returns the runtime tool search helper.
​
ensureServersConnected
() => Promise<void>
Protected helper that connects missing configured servers before execution.
​
getToolNamespaces
() => ToolNamespaceInfo[]
Protected helper that returns active server namespaces and tools, excluding the internal code_mode server.
Signature 
abstract class BaseCodeExecutor {
  constructor(client: MCPClient);
  abstract execute(code: string, timeout?: number): Promise<ExecutionResult>;
  abstract cleanup(): Promise<void>;
  public createSearchToolsFunction(): SearchToolsFunction;
  protected ensureServersConnected(): Promise<void>;
  protected getToolNamespaces(): ToolNamespaceInfo[];
}
  • Code Mode: guide to enabling Code Mode and choosing an executor.
  • MCPClient: complete client constructor, lifecycle, configuration, and session APIs.
  • Building agents: agent setup with MCP tools.