mcp-use - The fullstack MCP framework to develop MCP Apps for ChatGPT / Claude and MCP Servers for AI Agents.

MCPAgent keeps conversation history in memory by default. Successful run() and stream() calls store the user prompt and final assistant text as ProviderMessage[].

Keep conversation context

This example completes two turns, inspects the stored messages, and then clears them.

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

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

  try {
    await agent.initialize();

    await agent.run({ prompt: "My project codename is Cedar." });
    const answer = await agent.run({ prompt: "What is the project codename?" });
    console.log(answer);

    const history: ProviderMessage[] = agent.getConversationHistory();
    console.log(history.map(({ role, content }) => ({ role, content })));

    agent.clearConversationHistory();
    console.log(agent.getConversationHistory().length); // 0
  } finally {
    await agent.close();
  }
}

main().catch(console.error);

After two successful calls, history normally contains four messages: one user and one assistant message for each turn.

Know what is stored

Conversation history uses the provider-neutral ProviderMessage shape. Each message has a role and content; provider messages can also represent tool calls and results. The agent’s automatic memory is narrower:

run() and stream() append the prompt and final assistant text after a successful call.
Tool calls and tool results are not appended to automatic memory.
streamEvents() does not append any conversation history.
Per-call messages and externalHistory affect that call but are not copied into stored history.
A failed or aborted call does not append the prompt as a completed turn.

getConversationHistory() returns a new array. Changing that array does not replace agent memory, although message objects inside it are not deep-cloned.

Disable memory

Set memoryEnabled: false when every call must start with only the system prompt, per-call messages, and current prompt.

const agent = new MCPAgent({
  llm: "openai/gpt-4o",
  mcpServers,
  memoryEnabled: false,
});

await agent.initialize();
await agent.run({ prompt: "Remember the number 42." });
const result = await agent.run({ prompt: "What number did I give you?" });
console.log(result);
await agent.close();

With memory disabled, the second call does not receive the first turn from agent memory.

Persist history outside the agent

History lives only on the MCPAgent instance. It is not written to disk or restored after a process restart. Store getConversationHistory() in your application if you need durable conversations. Pass restored ProviderMessage values through messages for a later call:

const savedHistory: ProviderMessage[] = agent.getConversationHistory();

const result = await anotherAgent.run({
  messages: savedHistory,
  prompt: "Continue from the saved conversation.",
});

Passing messages provides context for that call. It does not seed anotherAgent’s internal history.

Clear a conversation

clearConversationHistory() removes all stored conversation messages immediately. The system prompt is held separately, so clearing history does not change it. Closing an agent does not clear its in-memory history. If you initialize the same instance again, its stored conversation remains until you clear it or discard the instance.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Memory management

Keep conversation context

Know what is stored

Disable memory

Persist history outside the agent

Clear a conversation

Next steps

​Keep conversation context

​Know what is stored

​Disable memory

​Persist history outside the agent

​Clear a conversation

​Next steps

Keep conversation context

Know what is stored

Disable memory

Persist history outside the agent

Clear a conversation

Next steps