> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Build AI agents that call MCP server tools, with LLM integration, streaming, structured output, and memory.

`MCPAgent` connects an LLM to one or more MCP servers. The agent discovers tools, resources, and prompts, exposes them to a LangChain-compatible chat model, runs a bounded multi-step loop, and returns the final answer.

Use `MCPAgent` when you want the model to decide which MCP tools to call. Use [`MCPClient`](https://docs.mcp-use.com/v1/typescript/client/index) directly when your application should choose exact tools, resources, or prompts itself.

## Key features

* **Tool-calling loop**: Give the agent a prompt and let the LLM call MCP tools until it can answer.
* **Simplified or explicit setup**: Pass `"provider/model"` plus `mcpServers`, or provide your own LangChain model and `MCPClient`.
* **Streaming**: Stream tool-call steps or low-level LangChain events as the agent runs.
* **Structured output**: Pass a Zod schema to get validated TypeScript data instead of plain text.
* **Conversation memory**: Keep previous turns across `run` calls by default.
* **Multi-server routing**: Enable Server Manager when many servers expose more tools than you want in context at once.

## Installation

Install `@mcp-use/agent`. `@mcp-use/client` is included as a dependency.

```bash npm theme={null}
npm install @mcp-use/agent
```

```bash pnpm theme={null}
pnpm add @mcp-use/agent
```

```bash bun theme={null}
bun add @mcp-use/agent
```

For the LangChain bridge (`import { MCPAgent } from "@mcp-use/agent/langchain"`) or when you pass an explicit LangChain chat model, also install the peers you use:

```bash OpenAI theme={null}
npm install langchain @langchain/openai
```

```bash Anthropic theme={null}
npm install langchain @langchain/anthropic
```

```bash Google theme={null}
npm install langchain @langchain/google-genai
```

```bash Groq theme={null}
npm install langchain @langchain/groq
```

Set the matching API key in your environment: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, or `GROQ_API_KEY`.

## Quick start

This example connects to the filesystem MCP server and answers a question about the current directory. It uses simplified mode, so the agent creates the LangChain model and `MCPClient` during initialization.

```typescript theme={null}
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: "What is in the current folder?" });
console.log(result);

await agent.close();
```

`agent.run()` returns the final answer as a string. `maxSteps` defaults to `5`; raise it for complex tasks with `new MCPAgent({ ..., maxSteps: 10 })` or per call with `agent.run({ prompt, maxSteps: 10 })`. Always call `agent.close()` when the agent owns its client, or when you want to shut down explicit client connections.

## Choose a setup mode

`MCPAgent` supports two construction patterns.

| Mode | Use it when | You provide |
| - | - | - |
| Simplified mode | You want the shortest path to a working agent. | `llm: "provider/model"` and `mcpServers`. |
| Explicit mode | You need full control over the LLM, client lifecycle, callbacks, custom tools, or connectors. | A LangChain chat model plus `MCPClient` or connectors. |

For constructor options, defaults, run options, memory methods, streaming signatures, and observability methods, see the [MCPAgent API Reference](https://docs.mcp-use.com/v1/typescript/api-reference/agent/mcp-agent.md).

## Core capabilities

### Structured output

Pass a Zod `schema` to `run` to get a typed object back instead of a string.

```typescript theme={null}
import { z } from "zod";

const result = await agent.run({
  prompt: "Analyze the file structure",
  schema: z.object({
    totalFiles: z.number(),
    fileTypes: z.array(z.string()),
    largestFile: z.string(),
  }),
});

console.log(result.totalFiles);
```

See [Structured Output](https://docs.mcp-use.com/v1/typescript/agent/structured-output.md) for details.

### Streaming

Iterate over `agent.stream` to receive each step as the agent runs.

```typescript theme={null}
for await (const step of agent.stream({ prompt: "Write a report" })) {
  console.log(`Tool: ${step.action.tool}`);
}
```

`agent.prettyStreamEvents` and `agent.streamEvents` give formatted and low-level output. See [Streaming](https://docs.mcp-use.com/v1/typescript/agent/streaming.md).

### Memory

Conversation memory is on by default, so the agent remembers earlier turns across `run` calls.

```typescript theme={null}
await agent.run({ prompt: "Hello, my name is Alice" });
await agent.run({ prompt: "What's my name?" });

agent.clearConversationHistory();
```

Pass `memoryEnabled: false` to `new MCPAgent({ ... })` to disable it. See [Memory Management](https://docs.mcp-use.com/v1/typescript/agent/memory-management.md).

## Next steps

> [card] [LLM Integration](https://docs.mcp-use.com/v1/typescript/agent/llm-integration.md)
>
> Connect OpenAI, Anthropic, Google, or Groq.

> [card] [Structured Output](https://docs.mcp-use.com/v1/typescript/agent/structured-output.md)
>
> Return typed responses with Zod schemas.

> [card] [Streaming](https://docs.mcp-use.com/v1/typescript/agent/streaming.md)
>
> Stream steps and events as the agent runs.

> [card] [Memory Management](https://docs.mcp-use.com/v1/typescript/agent/memory-management.md)
>
> Keep or reset conversation history across runs.

> [card] [Server Manager](https://docs.mcp-use.com/v1/typescript/agent/server-manager.md)
>
> Manage tools across multiple MCP servers.

> [card] [Observability](https://docs.mcp-use.com/v1/typescript/agent/observability.md)
>
> Trace and monitor agent runs.

> [card] [MCPAgent API Reference](https://docs.mcp-use.com/v1/typescript/api-reference/agent/mcp-agent.md)
>
> Check constructor options, method signatures, and types.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.