> ## 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`](/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` and one LangChain provider package for the LLM you want to use.
```bash npm theme={null}
npm install mcp-use
```
```bash pnpm theme={null}
pnpm add mcp-use
```
```bash yarn theme={null}
yarn add mcp-use
```
```bash OpenAI theme={null}
npm install @langchain/openai
```
```bash Anthropic theme={null}
npm install @langchain/anthropic
```
```bash Google theme={null}
npm install @langchain/google-genai
```
```bash Groq theme={null}
npm install @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";
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](/typescript/api-reference/agent/mcp-agent).
## 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](/typescript/agent/structured-output) 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](/typescript/agent/streaming).
### 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](/typescript/agent/memory-management).
## Next steps
Connect OpenAI, Anthropic, Google, or Groq.
Return typed responses with Zod schemas.
Stream steps and events as the agent runs.
Keep or reset conversation history across runs.
Manage tools across multiple MCP servers.
Trace and monitor agent runs.
Check constructor options, method signatures, and types.