---
title: "Introduction"
description: "Build AI agents powered by MCP servers"
icon: "list-start"
---

import { CodeSandbox } from '/snippets/codesandbox.jsx'

# 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
npm install mcp-use
```
```bash pnpm
pnpm add mcp-use
```
```bash yarn
yarn add mcp-use
```
</CodeGroup>

You'll also need a LangChain LLM provider package:

<CodeGroup>
```bash OpenAI
npm install @langchain/openai
```
```bash Anthropic
npm install @langchain/anthropic
```
```bash Google
npm install @langchain/google-genai
```
```bash Groq
npm install @langchain/groq
```
</CodeGroup>

## Quick Start

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

```typescript
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.5" });

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"></CodeSandbox>



## 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-5.5, gpt-5.5-mini)
- Anthropic (claude-opus-4-7, claude-sonnet-4-6)
- Google (gemini-3.1-pro, gemini-3.1-flash)
- 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
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
// 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
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>

