Native cross-platform MCP agent — connect an LLM to MCP servers, run a tool-calling loop, stream steps, and return answers. Works in Node and browser from the same import. Part of the mcp-use TypeScript framework.

Docs: Agent overview · API reference

Install

npm install @mcp-use/agent

Requires Node.js ≥ 22.22.2. @mcp-use/client is included as a dependency.

For the LangChain bridge (import { MCPAgent } from "@mcp-use/agent/langchain"), also install the peers you use, for example:

npm install langchain @langchain/openai

Quick start

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();

run({ prompt }) returns the final answer. Raise maxSteps for multi-tool tasks. Always call close() when the agent owns its client.

LangChain bridge

Use the same MCPAgent class name from a separate entry when you need LangChain models, Langfuse tracing, Server Manager, or AI SDK streaming:

import { ChatOpenAI } from "@langchain/openai";
import { MCPAgent } from "@mcp-use/agent/langchain";
import { MCPClient } from "@mcp-use/client";

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

const client = new MCPClient({ mcpServers });
const agent = new MCPAgent({
  llm: new ChatOpenAI({ model: "gpt-4o" }),
  client,
});

const result = await agent.run({ prompt: "Summarize the repo README" });
await agent.close();

Features

| Feature | Entry | Description | | --- | --- | --- | | Tool-calling loop | @mcp-use/agent | LLM discovers and calls MCP tools until it can answer | | Simplified setup | @mcp-use/agent | "provider/model" + mcpServers — no manual client/LLM wiring | | Streaming | @mcp-use/agent | stream() for steps, streamEvents() for native LLM events | | Structured output | @mcp-use/agent/langchain | Zod schema on run({ prompt, schema }) | | Memory | both | Conversation history across run() calls | | Server Manager | @mcp-use/agent/langchain | Dynamically add MCP servers during a run | | Observability | @mcp-use/agent/langchain | Langfuse metadata, tags, and trace flush | | Remote agent | @mcp-use/agent | Run against Manufact Cloud by agentId |

Package entry points

| Import | Environment | Description | | --- | --- | --- | | @mcp-use/agent | Node + browser | Native MCPAgent (fetch-based LLM drivers) | | @mcp-use/agent/langchain | Node | LangChain MCPAgent (optional peer deps) |

In the browser, pass HTTP MCP URLs or live connections from @mcp-use/client/react. Stdio command/args server configs are Node-only.

Examples

See examples/README.md. Run from this package:

OPENAI_API_KEY=... pnpm exec tsx examples/basic/simplified_agent_example.ts

Related packages

| Package | Description | | --- | --- | | @mcp-use/client | MCP client (HTTP, stdio, React hooks) | | mcp-use | Full framework (server + agent + client) | | @mcp-use/inspector | Web-based MCP debugger |

License

MIT