MCPAgent

View the source code for this module on GitHub:https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/agent/src/agents/mcp_agent.ts

MCPAgent connects a LangChain-compatible chat model to MCP servers. It discovers MCP tools, resources, and prompts, exposes them as LangChain tools, runs a multi-step agent loop, and returns either a string or a Zod-validated structured result. Related source files: types.ts, remote.ts, and agents/index.ts.

import { MCPAgent } from "@mcp-use/agent";

Import agent-specific exports from @mcp-use/agent:

import { MCPAgent } from "@mcp-use/agent";
import type {
  MCPAgentOptions,
  MCPServerConfig,
  LLMConfig,
} from "@mcp-use/agent";

Constructor

Creates an MCP agent. The constructor supports explicit mode, where you provide a model and MCPClient or connectors, and simplified mode, where you provide a "provider/model" string and mcpServers configuration. Parameters

MCPAgentOptions
required
Agent configuration. Use either ExplicitModeOptions or SimplifiedModeOptions.

Returns

MCPAgent

Signature

constructor(options: MCPAgentOptions)

Simplified mode

In simplified mode, MCPAgent creates the MCPClient and LLM during initialize(). The llm value must use the "provider/model" format.

import { MCPAgent } from "@mcp-use/agent";

const agent = new MCPAgent({
  llm: "openai/gpt-4o",
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "./"],
    },
  },
});

const result = await agent.run({
  prompt: "Summarize the files in this directory.",
});

console.log(result);
await agent.close();

Explicit mode

In explicit mode, you create the model and client yourself. Use this mode when you need full control over the LLM instance, client lifecycle, connectors, callbacks, or server manager.

import { ChatOpenAI } from "@langchain/openai";
import { MCPAgent } from "@mcp-use/agent";
import { MCPClient } from "@mcp-use/client";

const client = new MCPClient({
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "./"],
    },
  },
});

const agent = new MCPAgent({
  llm: new ChatOpenAI({ model: "gpt-4o" }),
  client,
  maxSteps: 10,
});

await agent.initialize();
const result = await agent.run({ prompt: "List the available tools." });

console.log(result);
await agent.close();

Methods

getPackageVersion

Returns the installed mcp-use package version. Returns

string

Signature

static getPackageVersion(): string

initialize

Connects to MCP servers, creates LangChain tools, builds the system message, configures observability callbacks, and creates the underlying LangChain agent executor. In simplified mode, this also creates the MCPClient and LLM from the constructor options. Returns

Promise<void>

Signature

initialize(): Promise<void>

run() initializes the agent when connector management is enabled. Call initialize() yourself when you want explicit lifecycle control before stream(), streamEvents(), or repeated runs.

run

Runs a prompt to completion and returns the final result. Without a schema, the result is a string. With a Zod schema, the result is parsed and returned as the schema’s inferred type. Parameters

string
required
User request to send to the agent.

number

default:"constructor maxSteps"

Maximum model-call steps for this run. The constructor default is 5.

boolean

default:"true"

Whether the agent should initialize connections before the run and clean up connector-only runs after completion.

BaseMessage[]

default:"undefined"

Additional LangChain-formatted history for this run. The native agent places stored memory first (when enabled), then externalHistory, messages, and the current prompt. Supplying it does not clear or replace stored memory.

ZodSchema<T>

default:"undefined"

Schema for structured output. When present, run() returns Promise<T>.

AbortSignal

default:"undefined"

Abort signal passed to the underlying LangChain execution.

Returns

Promise<string | T>

Example

import { z } from "zod";

const summary = await agent.run({
  prompt: "Inspect the project and summarize the package scripts.",
  maxSteps: 8,
});

const analysis = await agent.run({
  prompt: "Count the TypeScript files by directory.",
  schema: z.object({
    totalFiles: z.number(),
    directories: z.array(
      z.object({
        path: z.string(),
        count: z.number(),
      }),
    ),
  }),
});

Signature

run(options: RunOptions): Promise<string>
run<T>(options: RunOptions<T>): Promise<T>

The positional overloads (run(query, maxSteps, manageConnector, externalHistory, outputSchema, signal)) are still supported for compatibility, but they are deprecated. Prefer the options object form.

stream

Streams high-level agent steps and returns the final answer as the async generator’s return value. Each yielded step represents a tool call. Tool observations are logged internally and may be empty in the yielded object. Parameters

RunOptions<T>
required
Same options object accepted by run.

Yields

string
Name of the tool the agent called.

any
Arguments passed to the tool.

string
Short text description of the tool call.

string
Tool observation text when available.

Returns

AsyncGenerator<AgentStep, string | T, void>

Example

for await (const step of agent.stream({
  prompt: "Find the README and summarize it.",
  maxSteps: 6,
})) {
  console.log(step.action.tool, step.action.toolInput);
}

Signature

stream(options: RunOptions): AsyncGenerator<AgentStep, string, void>
stream<T>(options: RunOptions<T>): AsyncGenerator<AgentStep, T, void>

streamEvents

Streams low-level LangChain StreamEvent objects from the underlying agent executor. Use this method for token streaming, detailed progress UIs, and custom event handling. Parameters

RunOptions<T>
required
Same options object accepted by run.

Returns

AsyncGenerator<StreamEvent, void, void>

Example

for await (const event of agent.streamEvents({
  prompt: "Search the MCP server for project metadata.",
})) {
  if (event.event === "on_chat_model_stream") {
    const content = event.data?.chunk?.content ?? event.data?.chunk?.text;
    if (content) process.stdout.write(String(content));
  }
}

Signature

streamEvents(options: RunOptions): AsyncGenerator<StreamEvent, void, void>
streamEvents<T>(options: RunOptions<T>): AsyncGenerator<StreamEvent, void, void>

prettyStreamEvents

Streams low-level events through the built-in terminal formatter. This method is intended for CLIs and local development output. Parameters

RunOptions<T>
required
Same options object accepted by run.

Returns

AsyncGenerator<void, string, void>

Example

for await (const _ of agent.prettyStreamEvents({
  prompt: "List all available MCP tools.",
})) {
  // Output is printed by the formatter.
}

Signature

prettyStreamEvents(options: RunOptions): AsyncGenerator<void, string, void>
prettyStreamEvents<T>(options: RunOptions<T>): AsyncGenerator<void, string, void>

getConversationHistory

Returns a copy of the current conversation history. Conversation memory is enabled by default. Returns

BaseMessage[]

Signature

getConversationHistory(): BaseMessage[]

clearConversationHistory

Clears stored conversation history. When memory is enabled and a system message exists, the system message is preserved. Returns

void

Signature

clearConversationHistory(): void

getSystemMessage

Returns the active LangChain SystemMessage, or null before initialization when no system message has been created. Returns

SystemMessage | null

Signature

getSystemMessage(): SystemMessage | null

setSystemMessage

Replaces the active system message. If the agent is already initialized and tools are loaded, the underlying agent executor is recreated with the new message. Parameters

string
required
System message content.

Returns

void

Signature

setSystemMessage(message: string): void

setDisallowedTools

Sets the list of tool names that should not be exposed to the agent. If the agent is already initialized, reinitialize the agent for the change to affect generated tools. Parameters

string[]
required
Tool names to hide from the agent.

Returns

void

Signature

setDisallowedTools(disallowedTools: string[]): void

getDisallowedTools

Returns the current disallowed tool name list. Returns

string[]

Signature

getDisallowedTools(): string[]

setMetadata

Merges metadata into the current observability metadata. Keys are sanitized by replacing unsupported characters with underscores. Object values are serialized for validation and large serialized values are truncated. Parameters

Record<string, any>
required
Serializable key-value pairs to attach to observability traces.

Returns

void

Signature

setMetadata(newMetadata: Record<string, any>): void

getMetadata

Returns a copy of the current observability metadata. Returns

Record<string, any>

Signature

getMetadata(): Record<string, any>

setTags

Adds tags to observability traces. Tags are sanitized, deduplicated, and limited to 50 characters. Parameters

string[]
required
Tags to attach to observability traces.

Returns

void

Signature

setTags(newTags: string[]): void

getTags

Returns a copy of the current observability tags. Returns

string[]

Signature

getTags(): string[]

flush

Flushes observability traces through the configured ObservabilityManager. Use this in serverless functions before the function exits. Returns

Promise<void>

Signature

flush(): Promise<void>

close

Closes agent resources, shuts down observability handlers, clears tools and the executor, closes the client or disconnects direct connectors, and marks the agent as uninitialized. Returns

Promise<void>

Signature

close(): Promise<void>

Properties

toolsUsedNames

Public array of tool names called during agent execution. The array is appended to as runs execute. Type

string[]

observabilityManager

Public ObservabilityManager instance used to create callbacks, flush traces, and shut down observability integrations. Type

ObservabilityManager;

Types

MCPAgentOptions

Union of explicit and simplified constructor options. Signature

type MCPAgentOptions = ExplicitModeOptions | SimplifiedModeOptions;

ExplicitModeOptions

Options for constructing an agent from a pre-instantiated LLM plus an MCPClient or direct connectors. Fields

LanguageModel
required
LangChain-compatible chat model instance.

MCPClient
MCP client. Required when connectors is omitted and required for useServerManager.

BaseConnector[]
Direct connectors. Required when client is omitted.

number
Default maximum agent steps. Defaults to 5.

boolean
Initialize automatically when a run starts and connector management did not initialize the agent. Defaults to false.

boolean
Store conversation history across runs. Defaults to true.

string | null
System prompt override. Defaults to null.

string | null
Template override used when generating the system message from tools. Defaults to null.

string | null
Extra instructions appended to the generated system prompt. Defaults to null.

string[]
Tool names to hide from the agent. Defaults to [].

StructuredToolInterface[]
Extra LangChain tools to add after MCP tools are created. Defaults to [].

string[]
Initial tool usage list. Defaults to [].

boolean
Expose MCP resources as tools. Defaults to true.

boolean
Expose MCP prompts as tools. Defaults to true.

boolean
Use ServerManager tools instead of exposing all server tools directly. Defaults to false.

boolean
Enable verbose observability output. Defaults to false.

boolean
Enable observability callback setup. Defaults to true.

LangChainAdapter
Custom adapter for converting MCP tools, resources, and prompts to LangChain tools.

(client: MCPClient) => ServerManager
Factory for custom server manager instances.

BaseCallbackHandler[]
Custom LangChain callback handlers.

Signature

interface ExplicitModeOptions {
  llm: LanguageModel;
  client?: MCPClient;
  connectors?: BaseConnector[];
  maxSteps?: number;
  autoInitialize?: boolean;
  memoryEnabled?: boolean;
  systemPrompt?: string | null;
  systemPromptTemplate?: string | null;
  additionalInstructions?: string | null;
  disallowedTools?: string[];
  additionalTools?: StructuredToolInterface[];
  toolsUsedNames?: string[];
  exposeResourcesAsTools?: boolean;
  exposePromptsAsTools?: boolean;
  useServerManager?: boolean;
  verbose?: boolean;
  observe?: boolean;
  adapter?: LangChainAdapter;
  serverManagerFactory?: (client: MCPClient) => ServerManager;
  callbacks?: BaseCallbackHandler[];
}

SimplifiedModeOptions

Options for constructing an agent from an LLM string and MCP server configuration. The agent creates the LLM and client internally during initialization. Fields

string
required
LLM identifier in "provider/model" format, such as "openai/gpt-4o" or "anthropic/claude-sonnet-4-6".

Record<string, MCPServerConfig>
required
MCP server connection configuration keyed by server name.

LLMConfig
Provider-specific LLM configuration such as apiKey, temperature, maxTokens, and topP.

number
Default maximum agent steps. Defaults to 5.

boolean
Initialize automatically when a run starts and connector management did not initialize the agent. Defaults to false.

boolean
Store conversation history across runs. Defaults to true.

string | null
System prompt override. Defaults to null.

string | null
Template override used when generating the system message from tools. Defaults to null.

string | null
Extra instructions appended to the generated system prompt. Defaults to null.

string[]
Tool names to hide from the agent. Defaults to [].

StructuredToolInterface[]
Extra LangChain tools to add after MCP tools are created. Defaults to [].

boolean
Expose MCP resources as tools. Defaults to true.

boolean
Expose MCP prompts as tools. Defaults to true.

boolean
Use ServerManager tools instead of exposing all server tools directly. Defaults to false.

boolean
Enable verbose observability output. Defaults to false.

boolean
Enable observability callback setup. Defaults to true.

BaseCallbackHandler[]
Custom LangChain callback handlers.

Signature

interface SimplifiedModeOptions {
  llm: string;
  llmConfig?: LLMConfig;
  mcpServers: Record<string, MCPServerConfig>;
  maxSteps?: number;
  autoInitialize?: boolean;
  memoryEnabled?: boolean;
  systemPrompt?: string | null;
  systemPromptTemplate?: string | null;
  additionalInstructions?: string | null;
  disallowedTools?: string[];
  additionalTools?: StructuredToolInterface[];
  exposeResourcesAsTools?: boolean;
  exposePromptsAsTools?: boolean;
  useServerManager?: boolean;
  verbose?: boolean;
  observe?: boolean;
  callbacks?: BaseCallbackHandler[];
}

MCPServerConfig

Configuration for an MCP server in simplified mode. Fields

string
Command for a stdio server.

string[]
Arguments passed to command.

Record<string, string>
Environment variables for the server process.

string
URL for a remote HTTP MCP server.

Record<string, string>
Headers sent to remote MCP servers.

string
Bearer token value accepted by existing config shapes.

string
Bearer token value accepted by existing config shapes.

Signature

interface MCPServerConfig {
  command?: string;
  args?: string[];
  env?: Record<string, string>;
  url?: string;
  headers?: Record<string, string>;
  auth_token?: string;
  authToken?: string;
}

LLMConfig

Configuration passed to internally created LangChain model instances in simplified mode. Fields

string
Provider API key. If omitted, the provider-specific environment variable is used.

number
Sampling temperature.

number
Maximum output tokens.

number
Nucleus sampling value.

any
Additional provider-specific LangChain model options.

Signature

interface LLMConfig {
  apiKey?: string;
  temperature?: number;
  maxTokens?: number;
  topP?: number;
  [key: string]: any;
}

RunOptions

Options object accepted by run, stream, streamEvents, and prettyStreamEvents. Fields

string
required
User request to send to the agent.

number
Per-call step limit override.

boolean
Whether the agent manages initialization and connector cleanup for the call.

BaseMessage[]
Additional history appended after the native agent’s stored memory and before provider messages and the current prompt.

ZodSchema<T>
Zod schema for structured output.

AbortSignal
Abort signal for cancellation.

Signature

interface RunOptions<T = string> {
  prompt: string;
  maxSteps?: number;
  manageConnector?: boolean;
  externalHistory?: BaseMessage[];
  schema?: ZodSchema<T>;
  signal?: AbortSignal;
}

RunOptions is defined in the mcp_agent.ts source file. It is used structurally by the public methods, so you can pass an object with these fields without importing the interface.

Agent guide: task-focused guide for building MCP agents.
Streaming: guide for step streaming and low-level event streaming.
Structured output: guide for Zod schema results.
Observability: guide for tracing, metadata, and callbacks.

Overview

Server

React

Client

Agent

Constructor

Simplified mode

Explicit mode

Methods

getPackageVersion

initialize

run

stream

streamEvents

prettyStreamEvents

getConversationHistory

clearConversationHistory

getSystemMessage

setSystemMessage

setDisallowedTools

getDisallowedTools

setMetadata

getMetadata

setTags

getTags

flush

close

Properties

toolsUsedNames

observabilityManager

Types

MCPAgentOptions

ExplicitModeOptions

SimplifiedModeOptions

MCPServerConfig

LLMConfig

RunOptions

​Constructor

​Simplified mode

​Explicit mode

​Methods

​getPackageVersion

​initialize

​run

​stream

​streamEvents

​prettyStreamEvents

​getConversationHistory

​clearConversationHistory

​getSystemMessage

​setSystemMessage

​setDisallowedTools

​getDisallowedTools

​setMetadata

​getMetadata

​setTags

​getTags

​flush

​close

​Properties

​toolsUsedNames

​observabilityManager

​Types

​MCPAgentOptions

​ExplicitModeOptions

​SimplifiedModeOptions

​MCPServerConfig

​LLMConfig

​RunOptions

​Related

Constructor

Simplified mode

Explicit mode

Methods

getPackageVersion

initialize

run

stream

streamEvents

prettyStreamEvents

getConversationHistory

clearConversationHistory

getSystemMessage

setSystemMessage

setDisallowedTools

getDisallowedTools

setMetadata

getMetadata

setTags

getTags

flush

close

Properties

toolsUsedNames

observabilityManager

Types

MCPAgentOptions

ExplicitModeOptions

SimplifiedModeOptions

MCPServerConfig

LLMConfig

RunOptions

Related