McpClient

Defined in: src/mcp/client.ts:319

MCP client using SDK v2, including legacy task execution.

Example

const client = new McpClient({ url: 'https://example.com/mcp', tasksConfig: {} })
const agent = new Agent({ tools: [client] })

Constructors

Constructor

new McpClient(args): McpClient;

Defined in: src/mcp/client.ts:401

Parameters

Parameter	Type
args	McpClientConfig

Returns

McpClient

Properties

DEFAULT_TTL

readonly static DEFAULT_TTL: 60000 = 60000;

Defined in: src/mcp/client.ts:325

Default task lifecycle request timeout in milliseconds.

Deprecated

Use McpClient.DEFAULT_REQUEST_TIMEOUT.

---

DEFAULT_POLL_TIMEOUT

readonly static DEFAULT_POLL_TIMEOUT: 300000 = 300000;

Defined in: src/mcp/client.ts:328

Default overall task operation deadline in milliseconds.

---

DEFAULT_REQUEST_TIMEOUT

readonly static DEFAULT_REQUEST_TIMEOUT: 60000 = 60000;

Defined in: src/mcp/client.ts:331

Default task lifecycle request timeout in milliseconds.

---

DEFAULT_POLL_INTERVAL_MS

readonly static DEFAULT_POLL_INTERVAL_MS: 1000 = 1000;

Defined in: src/mcp/client.ts:334

Default polling interval when a legacy task response omits pollInterval.

Accessors

client

Get Signature

get client(): Client;

Defined in: src/mcp/client.ts:511

Returns

Client

---

serverCapabilities

Get Signature

get serverCapabilities(): any;

Defined in: src/mcp/client.ts:515

Returns

any

---

serverVersion

Get Signature

get serverVersion(): any;

Defined in: src/mcp/client.ts:519

Returns

any

---

serverInstructions

Get Signature

get serverInstructions(): string;

Defined in: src/mcp/client.ts:523

Returns

string

---

connectionState

Get Signature

get connectionState(): McpConnectionState;

Defined in: src/mcp/client.ts:527

Returns

McpConnectionState

---

clientName

Get Signature

get clientName(): string;

Defined in: src/mcp/client.ts:531

Returns

string

---

continueOnError

Get Signature

get continueOnError(): boolean;

Defined in: src/mcp/client.ts:535

Returns

boolean

---

onToolsChanged

Set Signature

set onToolsChanged(callback): void;

Defined in: src/mcp/client.ts:753

Sets a callback invoked when the MCP server’s tool list changes at runtime.

Parameters

Parameter	Type	Description
callback	(oldTools, newTools) => void	Handler receiving the previous tool names and the refreshed tool instances, or undefined to remove the callback.

Returns

void

Methods

loadServers()

static loadServers(
   config,
   defaults?,
   options?
): Promise<McpClient[]>;

Defined in: src/mcp/client.ts:344

Parses an MCP servers config (file path or object) and returns McpClient instances.

Parameters

Parameter	Type	Description
config	| string | Record<string, McpServerConfig>	A file path to a JSON config, or a flat server map object.
defaults?	McpClientOptions	Options applied to all clients unless overridden per-server.
options?	McpLoadServersOptions	Loader behavior, such as prefixing tools with the server name.

Returns

Promise<McpClient[]>

An array of McpClient instances ready to be passed to an Agent.

---

connect()

connect(reconnect?, options?): Promise<void>;

Defined in: src/mcp/client.ts:569

Connects the MCP client to the server.

Called lazily before any operation that requires a connection. When continueOnError is true, connection failures are swallowed and the client enters a 'failed' state. Subsequent calls are then no-ops until connect(true) is called explicitly to retry.

A client configured with url retries on a fresh transport and connection. A client configured with a transport instance reuses it, so the retry only works when that transport can be started again (a StreamableHTTPClientTransport cannot, so construct a new McpClient instead).

Parameters

Parameter	Type	Default value	Description
reconnect	boolean	false	When true, forces a reconnect even if already connected or failed.
options?	{ signal?: AbortSignal; }	undefined	Optional abort signal that stops this caller’s wait. The connection attempt itself continues for other callers awaiting it.
options.signal?	AbortSignal	undefined	-

Returns

Promise<void>

A promise that resolves when the connection is established.

---

disconnect()

disconnect(): Promise<void>;

Defined in: src/mcp/client.ts:652

Disconnects the MCP client from the server and cleans up resources.

Returns

Promise<void>

A promise that resolves when the disconnection is complete.

---

[asyncDispose]()

asyncDispose: Promise<void>;

Defined in: src/mcp/client.ts:669

Enables the await using pattern for automatic resource cleanup. Delegates to McpClient.disconnect.

Returns

Promise<void>

---

listTools()

listTools(options?): Promise<McpTool[]>;

Defined in: src/mcp/client.ts:685

Lists the tools available on the server and returns them as executable McpTool instances.

A prefix renames tools for the agent only; tools are always invoked, and matched by string and RegExp filters, under their server-side name. Overlong prefixed names are skipped with a warning when continueOnError is true; otherwise, listing throws. Unprefixed names are not length-checked.

Parameters

Parameter	Type	Description
options?	McpListToolsOptions	Overrides for the prefix and filters set on the client. An omitted field uses the client’s value; an explicit empty string or empty object disables it.

Returns

Promise<McpTool[]>

A promise that resolves with an array of McpTool instances.

Throws

ToolValidationError When a prefixed name exceeds the registry limit and continueOnError is false.

---

listPrompts()

listPrompts(options?): Promise<ListPromptsResult>;

Defined in: src/mcp/client.ts:791

Lists the prompts available on the server.

Without a paginationToken the client aggregates every page into one result with no nextCursor, and throws ListPaginationExceeded when the server pages past listMaxPages (64 unless configured). With a token it fetches a single page whose nextCursor feeds the next call.

Parameters

Parameter	Type	Description
options?	McpListOptions	Pagination options.

Returns

Promise<ListPromptsResult>

A promise that resolves with the raw MCP list prompts result.

Throws

Error when an earlier connect attempt failed with continueOnError set. Call connect(true) to retry.

---

getPrompt()

getPrompt(promptId, args?): Promise<GetPromptResult>;

Defined in: src/mcp/client.ts:804

Retrieves a prompt from the server by name.

Parameters

Parameter	Type	Description
promptId	string	The name of the prompt to retrieve.
args?	Record<string, string>	Arguments for the prompt’s template substitution.

Returns

Promise<GetPromptResult>

A promise that resolves with the raw MCP prompt result.

Throws

Error when an earlier connect attempt failed with continueOnError set. Call connect(true) to retry.

---

listResources()

listResources(options?): Promise<ListResourcesResult>;

Defined in: src/mcp/client.ts:821

Lists the resources available on the server.

Without a paginationToken the client aggregates every page into one result with no nextCursor, and throws ListPaginationExceeded when the server pages past listMaxPages (64 unless configured). With a token it fetches a single page whose nextCursor feeds the next call.

Parameters

Parameter	Type	Description
options?	McpListOptions	Pagination options.

Returns

Promise<ListResourcesResult>

A promise that resolves with the raw MCP list resources result.

Throws

Error when an earlier connect attempt failed with continueOnError set. Call connect(true) to retry.

---

readResource()

readResource(uri): Promise<ReadResourceResult>;

Defined in: src/mcp/client.ts:833

Reads a resource from the server.

Parameters

Parameter	Type	Description
uri	string | URL	The URI of the resource to read.

Returns

Promise<ReadResourceResult>

A promise that resolves with the raw MCP resource content.

Throws

Error when an earlier connect attempt failed with continueOnError set. Call connect(true) to retry.

---

listResourceTemplates()

listResourceTemplates(options?): Promise<ListResourceTemplatesResult>;

Defined in: src/mcp/client.ts:850

Lists the resource templates available on the server.

Without a paginationToken the client aggregates every page into one result with no nextCursor, and throws ListPaginationExceeded when the server pages past listMaxPages (64 unless configured). With a token it fetches a single page whose nextCursor feeds the next call.

Parameters

Parameter	Type	Description
options?	McpListOptions	Pagination options.

Returns

Promise<ListResourceTemplatesResult>

A promise that resolves with the raw MCP list resource templates result.

Throws

Error when an earlier connect attempt failed with continueOnError set. Call connect(true) to retry.

---

callTool()

callTool(
   tool,
   args,
   options?
): Promise<JSONValue>;

Defined in: src/mcp/client.ts:869

Invoke a tool on the connected MCP server using an McpTool instance.

When tasksConfig is set, task-backed execution is completed automatically on both server generations: SEP-2663 tasks on servers that advertise the tasks extension, and the legacy 2025-11-25 task protocol. Direct tool results are returned unchanged.

Parameters

Parameter	Type	Description
tool	McpTool	The McpTool instance to invoke.
args	JSONValue	The arguments to pass to the tool.
options?	McpCallToolOptions	Optional settings for the request.

Returns

Promise<JSONValue>

The final tool result.

Throws

McpTaskCancelledError When the server reports a cancelled task.

Throws

McpTaskFailedError When the server reports a failed task.

---

submitTool()

submitTool(
   tool,
   args,
   options?
): Promise<any>;

Defined in: src/mcp/client.ts:912

Invokes a tool once and returns either its direct result or a server-created task handle.

This operation never polls or consumes a returned task handle. Task creation is controlled by the server; the client only advertises support when tasksConfig is configured.

Parameters

Parameter	Type	Description
tool	McpTool	The McpTool instance to invoke.
args	JSONValue	The arguments to pass to the tool.
options?	McpCallToolOptions	Optional settings for the request.

Returns

Promise<any>

The direct tool result or task handle returned by the server.

---

getTask()

getTask(taskId, options?): Promise<McpGetTaskResult>;

Defined in: src/mcp/client.ts:961

Retrieves the current state of a SEP-2663 task.

Parameters

Parameter	Type	Description
taskId	string	Server-issued task identifier.
options?	McpTaskRequestOptions	Optional lifecycle request settings.

Returns

Promise<McpGetTaskResult>

The validated task state, including terminal result or error data when present.

---

updateTask()

updateTask(
   taskId,
   inputResponses,
   options?
): Promise<McpUpdateTaskResult>;

Defined in: src/mcp/client.ts:982

Supplies one or more responses to outstanding task input requests.

Partial response sets are supported; the server may keep the task in input_required until every outstanding request has been answered.

Parameters

Parameter	Type	Description
taskId	string	Server-issued task identifier.
inputResponses	McpInputResponses	Responses keyed by the corresponding input request key.
options?	McpTaskRequestOptions	Optional lifecycle request settings.

Returns

Promise<McpUpdateTaskResult>

The server’s validated acknowledgement.

---

cancelTask()

cancelTask(taskId, options?): Promise<McpCancelTaskResult>;

Defined in: src/mcp/client.ts:1011

Requests cooperative cancellation of a SEP-2663 task.

A successful acknowledgement does not guarantee that the server stopped the work or that the task will eventually report cancelled.

Parameters

Parameter	Type	Description
taskId	string	Server-issued task identifier.
options?	McpTaskRequestOptions	Optional lifecycle request settings.

Returns

Promise<McpCancelTaskResult>

The server’s validated acknowledgement.