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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://mcp-use.com/docs/feedback

```json
{
  "path": "/typescript/agent/index",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Introduction

> Build AI agents powered by MCP servers

export const CodeSandbox = ({title, id}) => {
  return <a href={`https://codesandbox.io/p/devbox/${id}?embed=1`}>
        <img noZoom src={`https://codesandbox.io/static/img/play-codesandbox.svg`} alt={title} />
    </a>;
};

# MCP Agents

**mcp-use** provides a complete agent framework for building AI applications that leverage MCP servers. The MCPAgent combines LLM integration, tool orchestration, and memory management to create powerful, autonomous AI agents.

## Key Features

* **LLM Integration**: Support for OpenAI, Anthropic, Google, and Groq
* **Automatic tool calling**: Agents automatically select and execute appropriate tools
* **Multi-server orchestration**: Connect to multiple MCP servers simultaneously
* **Structured output**: Type-safe responses with Zod schema validation
* **Streaming support**: Real-time streaming of agent responses
* **Memory management**: Built-in conversation history and context management

## Installation

The agent framework is included with the mcp-use package:

<CodeGroup>
  ```bash npm theme={null}
  npm install mcp-use
  ```

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

  ```bash yarn theme={null}
  yarn add mcp-use
  ```
</CodeGroup>

You'll also need a LangChain LLM provider package:

<CodeGroup>
  ```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
  ```
</CodeGroup>

## Quick Start

Here's a basic example of creating and running an agent:

```typescript theme={null}
import { MCPAgent, MCPClient } from "mcp-use";
import { ChatOpenAI } from "@langchain/openai";

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

const llm = new ChatOpenAI({ model: "gpt-5.1" });

const agent = new MCPAgent({ llm, client, maxSteps: 50 });

agent.run({ 
  prompt: "What is in the current folder?" 
}).then(async (response) => {
  console.log(response);
  await agent.close();
});
```

<CodeSandbox title="Edit mcp-use-get-started-agent" id="sweet-drake-m76ys6" />

## Architecture Overview

The MCPAgent framework is built around several core components that work together to enable intelligent, tool-using AI applications.

### **Agent Core**

The `MCPAgent` class orchestrates all agent functionality, managing LLM interactions, tool execution, and response generation.

**Learn more**: [Agent Configuration →](/typescript/agent/agent-configuration)

### **LLM Integration**

Native support for multiple LLM providers with a unified interface. Each provider is automatically detected and configured based on the LLM instance you provide.

**Supported providers**:

* OpenAI (GPT-3.5, GPT-4, GPT-4 Turbo)
* Anthropic (Claude 3 family)
* Google (Gemini models)
* Groq (Llama, Mixtral, and more)

**Learn more**: [LLM Integration →](/typescript/agent/llm-integration)

### **Tool Orchestration**

Agents automatically discover tools from connected MCP servers and intelligently select the right tools for each task. The framework handles:

* Tool discovery and schema conversion
* Automatic tool selection by the LLM
* Parameter validation and type safety
* Error handling and retries
* Multi-step workflows

**Learn more**: [Client Configuration →](/typescript/client/client-configuration)

### **Structured Output**

Generate type-safe responses with Zod schema validation. The agent can return structured data instead of plain text, enabling programmatic use of agent results.

```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()
  })
})

// result is fully typed!
console.log(result.totalFiles)
```

**Learn more**: [Structured Output →](/typescript/agent/structured-output)

### **Streaming**

Stream agent responses in real-time for better user experience and immediate feedback:

```typescript theme={null}
// Step-by-step streaming
for await (const step of agent.stream({ prompt: 'Write a report' })) {
  console.log(`Tool: ${step.action.tool}`)
}

// Pretty formatted streaming (great for CLI tools)
for await (const _ of agent.prettyStreamEvents({ 
  prompt: 'Analyze the codebase',
  maxSteps: 20 
})) {
  // Automatic syntax highlighting and formatting
}

// Low-level event streaming
for await (const event of agent.streamEvents({ prompt: 'Generate content' })) {
  if (event.event === 'on_chat_model_stream') {
    process.stdout.write(event.data?.chunk?.content || '')
  }
}
```

**Learn more**: [Streaming →](/typescript/agent/streaming)

### **Memory Management**

Control conversation history with built-in memory management. The agent automatically maintains context across multiple interactions:

```typescript theme={null}
const agent = new MCPAgent({
  llm,
  client,
  memoryEnabled: true  // Enable automatic memory management
})

await agent.run({ prompt: "Hello, my name is Alice" })
await agent.run({ prompt: "What's my name?" })  // Agent remembers Alice

// Clear history when needed
agent.clearConversationHistory()
```

**Learn more**: [Memory Management →](/typescript/agent/memory-management)

## Next Steps

<CardGroup cols={3}>
  <Card title="Agent Configuration" icon="cog" href="/typescript/agent/agent-configuration">
    Configure your agent and LLM settings
  </Card>

  <Card title="LLM Integration" icon="brain-circuit" href="/typescript/agent/llm-integration">
    Integrate with OpenAI, Anthropic, Google, or Groq
  </Card>

  <Card title="Structured Output" icon="braces" href="/typescript/agent/structured-output">
    Generate type-safe responses with Zod schemas
  </Card>
</CardGroup>