build-mcp-use-agent（构建 MCP USE Agent）

Build MCP Use Agent

Build production-grade TypeScript agents with MCPAgent from mcp-use. This skill drives both greenfield builds and audits of existing agent code.

Behavioral flow — what to do when this skill is invoked

Step 1 — Detect what exists

Run tree -L 3 or ls -R in the user's working directory. Look for signs of an existing mcp-use agent:

• package.json with "mcp-use" as a dependency
• Files importing MCPAgent from "mcp-use"
• MCPAgent constructor calls
• agent.run() / agent.stream() / agent.streamEvents() usage
• LangChain model imports (@langchain/openai, @langchain/anthropic, etc.)

Step 2A — Existing mcp-use agent found

When you find an existing implementation, deploy four parallel subagents to explore and diagnose it. Each subagent must read the relevant reference files and surface three things: what is correct, what is wrong, and what is missing.

If the runtime cannot spawn subagents, do the same four audits sequentially in the order below and keep the same output contract.

Subagent 1 — Agent configuration audit Explore: constructor options, initialization mode (explicit vs simplified), LLM choice and provider, maxSteps setting, autoInitialize, prompt customization. Read: references/guides/agent-configuration.md, references/guides/llm-integration.md

Subagent 2 — Execution and output audit Explore: run() / stream() / streamEvents() / prettyStreamEvents() usage, structured output with Zod, memory management, multi-turn behavior. Read: references/guides/streaming.md, references/guides/structured-output.md, references/guides/memory-management.md

Subagent 3 — MCP server connections audit Explore: MCPClient configuration, server definitions, server manager usage, tool exposure settings, resource/prompt exposure. Read: references/guides/server-manager.md, references/guides/quick-start.md

Subagent 4 — Production readiness audit Explore: observability (metadata, tags, callbacks, Langfuse), error handling, lifecycle management (close(), flush()), anti-patterns. Read: references/guides/observability.md, references/patterns/production-patterns.md, references/patterns/anti-patterns.md, references/troubleshooting/common-errors.md

After all subagents report back:

1. Synthesize findings into a prioritized list (critical issues first, then improvements, then nice-to-haves).
2. Apply improvements directly — fix bugs, add missing cleanup, correct wrong signatures, improve configuration.
3. Only ask the user if something is genuinely ambiguous (e.g., which LLM provider they want to switch to).

Step 2B — No existing mcp-use agent found

Check for context: is there an existing application that could benefit from an agent (e.g., an Express server, a CLI tool, a Next.js app)?

If context exists: Infer what kind of agent fits and build it. Read references/guides/quick-start.md and references/examples/integration-recipes.md for the right integration pattern. If the task is calculator-style and the repo does not already expose calculator tools, use the calculator server section in references/guides/quick-start.md before wiring the agent.

If no context exists: Ask the user up to 10 questions, each with 5+ concrete options:

1. What LLM provider? (OpenAI gpt-4o, Anthropic claude-sonnet-4-6 or claude-opus-4-7, Google gemini-2.5-flash or gemini-2.5-pro, Groq llama-3.3-70b-versatile, other)
2. Initialization mode? (Explicit — hand-built LLM and client, Simplified — "provider/model" string shorthand)
3. What MCP servers to connect? (filesystem, database, custom stdio, remote HTTP/SSE, none yet)
4. Output format? (plain text via run(), structured Zod schema, streaming steps, streaming tokens, pretty terminal)
5. Memory behavior? (stateful multi-turn conversation, stateless single-shot, manual history injection)
6. Need observability? (Langfuse auto-init, Langfuse custom endpoint, custom callbacks, none)
7. Execution environment? (CLI script, HTTP handler, serverless function, Next.js route, REPL/chat loop)
8. Max steps? (5 default, 10-20 for complex tasks, 30+ for code-mode workflows)
9. Tool restrictions? (block dangerous tools via disallowedTools, inject extra tools via additionalTools, control resource/prompt surface via exposeResourcesAsTools / exposePromptsAsTools, no restrictions)
10. Advanced needs? (code mode, server manager for multi-server routing, provider failover, none)

Then build the agent using the quick start patterns below and the relevant references.

Fast default for tiny, well-scoped tasks: if the task is simple and the working directory already makes the choice obvious, skip the long questionnaire and use these defaults unless the repo says otherwise:

• simplified mode
• llm: "openai/gpt-4o"
• maxSteps: 10
• memoryEnabled: false
• autoInitialize: true
• one clearly relevant MCP server only

Before the first run() / stream() / streamEvents() call, verify the provider key and every MCP server command or URL. Fix missing prerequisites first instead of debugging agent logic against a broken runtime.

Reference routing — curiosity-driven

Read these when the situation calls for it. Each trigger tells you *why* you would want that file.

Quick start

Explicit mode

Use when you need full control over the model instance, MCPClient, callbacks, or client options like code mode.

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

// MCPClient accepts a second MCPClientOptions argument for codeMode,
// onSampling, onElicitation, onNotification handlers. Omit it for plain agents.
const client = new MCPClient({
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", process.cwd()],
    },
  },
});

const llm = new ChatOpenAI({ model: "gpt-4o", temperature: 0 });

const agent = new MCPAgent({
  llm,
  client,
  maxSteps: 20,
  autoInitialize: true,
});

try {
  const result = await agent.run({
    prompt: "List the top-level files and summarize what each one does.",
  });
  console.log(result);
} finally {
  await agent.close();
}

Simplified mode

Use when you want the shortest correct setup. Pass llm as a "provider/model" string and mcpServers directly on the agent.

import { MCPAgent } from "mcp-use";

const agent = new MCPAgent({
  llm: "openai/gpt-4o",
  llmConfig: { temperature: 0 },
  mcpServers: {
    filesystem: {
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", process.cwd()],
    },
  },
  maxSteps: 20,
  autoInitialize: true,
});

try {
  const result = await agent.run({ prompt: "List the top-level files." });
  console.log(result);
} finally {
  await agent.close();
}

Build sequence

1. Pick explicit mode if you already have a LangChain model instance or need client options.
2. Pick simplified mode for compact scripts and server routes.
3. Set maxSteps deliberately — default is 5, which is low for most real tasks.
4. Validate provider env vars and MCP server command/URL before the first execution call.
5. If autoInitialize stays false, call await agent.initialize() or pre-create sessions before run() / stream() / streamEvents().
6. Use object-form run({prompt,...}) for production code.
7. Wrap every agent in try/finally with await agent.close().
8. Add streaming only after the non-streaming path works.
9. Add observability after the response path is stable.

Core API summary

Initialization modes

Key constructor options

For the full options table with all defaults, read references/guides/agent-configuration.md.

run() signatures

RunOptions fields: prompt (required), maxSteps, manageConnector (defaults to true — pass false when the caller owns connector lifetime), externalHistory (override conversation history for this call), schema (Zod schema for typed output), signal (AbortSignal). Tags and metadata are agent-wide, not per-call — set them via agent.setTags([...]) and agent.setMetadata({...}) before calling run().

Streaming methods

Critical: Prefer the options-object form for all three streaming methods: stream({prompt, maxSteps?, schema?, signal?}), streamEvents({prompt,...}), and prettyStreamEvents({prompt,...}). The plain-string overloads still work, but they are deprecated compatibility paths.

AgentStep type reference

Each step yielded by stream() represents one tool-call cycle. step.observation is empty ("") when yielded — tool results are tracked internally.

interface AgentStep {
  action: {
    tool: string;     // Tool selected by the agent
    toolInput: any;   // Arguments passed to the tool (any — could be string, object, etc.)
    log: string;      // LLM reasoning text — often empty in tool-calling agents
  };
  observation: string;  // Always "" at yield time
}

step.action.log is often empty in tool-calling agents because the model emits the intent through structured tool calls rather than reasoning text. The underlying LangChain runtime sometimes attaches messageLog: BaseMessage[] and toolCallId: string to the same action object — they are not declared on mcp-use's AgentStep, so cast to any to inspect them. Prefer those for correlating tool calls with on_tool_start / on_tool_end events emitted by streamEvents(). Also: do not JSON.stringify(step.action.toolInput) blindly — when it's already a string the result is double-encoded.

streamEvents() example

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

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

for await (const event of agent.streamEvents({ prompt: "Explain the architecture." })) {
  if (event.event === "on_chat_model_stream") {
    const text = event.data?.chunk?.text ?? event.data?.chunk?.content;
    if (typeof text === "string") process.stdout.write(text);
  }
}

Key streamEvents event types

Lifecycle methods

Langfuse auto-initialization

When LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY env vars are set, mcp-use auto-initializes Langfuse tracing. No manual CallbackHandler import needed. Only use explicit callbacks for custom Langfuse endpoints.

flush() + close() in serverless

In serverless environments (Next.js API routes, Lambda, Cloud Functions), always flush before closing to ensure traces reach the backend:

try {
  const result = await agent.run({ prompt: "Inspect the repository." });
  return result;
} finally {
  await agent.flush();   // send buffered traces
  await agent.close();   // clean up sessions
}

Code mode note

codeMode is configured on MCPClient, not on MCPAgent. When the task involves code execution, wire the client first:

const client = new MCPClient(
  { mcpServers: { /* ... */ } },
  { codeMode: true }
);
const agent = new MCPAgent({ llm, client, maxSteps: 30 });

For advanced code-mode patterns, read references/guides/advanced-patterns.md.

Companion packages

mcp-use@1.25.0 requires LangChain v1 and Zod v4 as peers. The full mcp-use surface includes: MCPAgent, MCPClient, MCPSession, RemoteAgent, connector classes (StdioConnector, HttpConnector, BaseConnector), loadConfigFile, ServerManager, ObservabilityManager, Telemetry, OAuth helpers (BrowserOAuthClientProvider, onMcpAuthorization, probeAuthParams), code-execution ancillaries (BaseCodeExecutor, E2BCodeExecutor, VMCodeExecutor), elicitation helpers (accept, decline, reject, validate), and PROMPTS.

Declared peer dependencies

All @langchain/*, langchain, langfuse, langfuse-langchain, and @e2b/code-interpreter are marked optional in peerDependenciesMeta — install only the providers you actually use. zod, react, and react-router are strictly required.

Optional LLM adapters (NOT peer-declared)

Both must remain LangChain v1 compatible. The "google/..." and "groq/..." simplified-mode shorthands fail at runtime if the matching adapter is missing.

Other helpers

If your codebase is on LangChain v0.x or Zod v3, plan the upgrade before adopting mcp-use@1.25.0 — peer-dep mismatches surface as runtime tool-calling failures and JSON-schema serialization bugs.

Provider quick reference

@langchain/google-genai and @langchain/groq are not declared peers of mcp-use@1.25.0; install them separately if you use those providers. Anthropic models: prefer claude-opus-4-7 for deep reasoning, claude-sonnet-4-6 for general MCP-agent workloads. Verify Google and Groq model IDs against their respective consoles before shipping — model IDs are deprecated frequently.

For full provider details, failover, and custom adapters, read references/guides/llm-integration.md.

Server manager quick reference

When useServerManager: true is set, the agent gains five built-in management tools:

For dynamic server switching and multi-server patterns, read references/guides/server-manager.md.

Rules

1. Use import {MCPAgent, MCPClient} from "mcp-use" — never import from @modelcontextprotocol/sdk in agent code.
2. Set maxSteps intentionally; explain the chosen value.
3. Close the agent with await agent.close() in try/finally in every example.
4. Put secrets in environment variables, never string literals.
5. Use object-form run() in production code and typed flows.
6. Prefer the options-object form for stream(), streamEvents(), and prettyStreamEvents(); the plain-string overloads still exist but are deprecated.
7. Use the object form whenever you need schema, maxSteps, signal, or other per-call controls.
8. prettyStreamEvents() also has a deprecated plain-string overload, but the object form is the stable shape to document and extend.
9. step.observation is always empty at yield time — never claim it contains tool output.
10. Call flush() before close() in serverless environments.
11. Langfuse auto-initializes via env vars — do not manually wire CallbackHandler unless using a custom endpoint.
12. Call client.closeAllSessions() when managing client lifetime separately from the agent.
13. codeMode is configured on MCPClient, not on MCPAgent.
14. Treat useServerManager as advanced — do not enable by default.
15. Explain memory behavior whenever showing multi-turn code.
16. Check both chunk.text and chunk.content for cross-provider streaming compatibility.
17. Use mcp-use structured output events (on_structured_output, on_structured_output_progress, on_structured_output_error) — not generic LangChain events.

Common pitfalls

Do / Don't

Minimal reading sets

"I need a minimal agent now"

• references/guides/quick-start.md
• references/guides/llm-integration.md

"I need to choose constructor options"

• references/guides/agent-configuration.md
• references/guides/quick-start.md

"I need streaming output"

• references/guides/streaming.md
• references/examples/integration-recipes.md

"I need structured output"

• references/guides/structured-output.md
• references/guides/streaming.md

"I need observability and production safety"

• references/guides/observability.md
• references/patterns/production-patterns.md
• references/patterns/anti-patterns.md

"I need advanced execution or code mode"

• references/guides/agent-configuration.md
• references/guides/advanced-patterns.md
• references/examples/agent-recipes.md

"Something is broken"

• references/troubleshooting/common-errors.md
• references/patterns/anti-patterns.md

Guardrails

• Do not import MCP SDK primitives directly — use mcp-use.
• Do not omit cleanup from long-lived examples.
• Do not describe codeMode as an MCPAgent constructor field.
• Do not recommend raw streamEvents() when prettyStreamEvents() or stream() suffices.
• Do not leave maxSteps unexplained in production examples.
• Do not hard-code secrets in copyable snippets.
• Do not enable useServerManager by default.
• Do not answer with thin pseudo-code when runnable TypeScript is needed.
• Do not add new reference files unless a topic cannot fit the routed structure.
• Do not break the header and routing conventions of sibling build-mcp-use-* skills.