Build MCP Use Agent

Build or audit TypeScript MCPAgent code from the mcp-use package — the LLM-driven loop where a model chooses, calls, and chains MCP tools across one or more servers.

This SKILL.md is a routing spine. Load-bearing rules and the minimal runnable path live here; deep detail lives in references/.

When to use this skill

Trigger on any of these:

• Imports MCPAgent from mcp-use and calls agent.run({ prompt }), agent.stream(...), agent.streamEvents(...), or agent.prettyStreamEvents(...).
• Wires an LLM (LangChain ChatModel or "provider/model" shorthand) into an agent loop that must select tools at runtime.
• Builds a Next.js / Express / serverless handler whose body is a MCPAgent invocation against one or more MCP servers.
• Adds streaming, structured output (Zod), memory, server-manager, code mode, observability (Langfuse), or production hardening to an existing MCPAgent.
• Debugging an agent that loops, stalls, hits maxSteps, leaks sessions, or returns wrong-shaped output.
• Picks a model/provider for an MCPAgent (OpenAI, Anthropic, Google, Groq, custom LangChain adapter) or migrates between them.

Do NOT use this skill for

• Pure deterministic MCPClient work — listing tools, manually calling a known tool, reading resources, sessions, React hooks, mcp-use/browser, npx mcp-use client. Route to build-mcp-use-client.
• Building the MCP server itself — tools, resources, prompts, auth, transports, MCP Apps widgets, Inspector, deploy. Route to build-mcp-use-server.
• Raw @modelcontextprotocol/* SDK servers (no mcp-use wrapper). Route to build-mcp-server-sdk-v1 or build-mcp-server-sdk-v2.
• LangChain/LangGraph agent code where MCP is optional or absent. Route to build-langchain-ts-app.

Rule of thumb: if an LLM decides which MCP tool to call, this skill. If the app already knows which MCP call to make, build-mcp-use-client. If you are writing the server, build-mcp-use-server.

Core rules (load-bearing — read before editing agent code)

Workflow

1. Scan the target. Inspect the actual package or app path. Look for package.json, mcp-use, imports of MCPAgent / MCPClient, agent.run(), agent.stream(), agent.streamEvents(), LangChain provider packages, server configs, existing cleanup.
2. Classify the work.
   • Existing agent: audit configuration, execution/output, MCP connections, production readiness against the rule table above.
   • New agent in an existing app: infer the smallest useful integration and wire it into the local structure.
   • New standalone agent: use the minimal runnable path below, then add only requested capabilities.
3. Verify current package facts (Rule 5) before writing runtime, peer, or setup claims.
4. Choose construction mode.
   • Simplified mode: llm: "provider/model" plus inline mcpServers. Best for scripts, demos, compact handlers.
   • Explicit mode: LangChain model instance plus MCPClient. Best for shared clients, code mode, callbacks, custom providers, lifecycle ownership. For deterministic client work that does not run the agent loop, route to build-mcp-use-client.
5. Build the non-streaming path first. Get one run({ prompt }) call working before adding streaming, structured output, memory, observability, or server manager.
6. Harden deliberately. Add maxSteps, memory policy, tool restrictions, env validation, cleanup, runtime checks, observability — based on the target environment.
7. Validate honestly. At minimum run TypeScript / package checks or the relevant script. Claim live MCP+LLM behavior only after running against a real server and key.

Minimal runnable path

The only inline example in this spine. Expanded variants live in references/guides/quick-start.md and references/examples/agent-recipes.md.

import "dotenv/config";
import { MCPAgent } from "mcp-use";

if (!process.env.OPENAI_API_KEY) {
  throw new Error("OPENAI_API_KEY is required.");
}

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

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

Before the first call, validate provider env vars and each MCP server command or URL. Debug broken prerequisites before changing agent logic.

Completion contract

• run() resolves to the final value (string or schema-typed result).
• stream() yields AgentStep objects; the final value appears only when the generator completes (done === true from .next()).
• streamEvents() yields raw lifecycle events and does not return a final value. Consume events such as on_chain_end and tool/model events.
• For structured output with streamEvents(), the mcp-use structured result is event.data.output on on_structured_output.
• step.observation from stream() is empty at yield time; use streamEvents() for live tool-result payloads.

Configuration and lifecycle contract

• Simplified mode: configuration lives inline on MCPAgent via mcpServers; the agent owns the generated client.
• Explicit mode: build an MCPClient from inline config or config-file helpers, then pass client to MCPAgent.
• codeMode lives on MCPClient, not MCPAgent.
• Cleanup policy:
  • Simplified mode or agent-owned client → await agent.close().
  • Explicit, shared client owned outside the agent → close the owner once at app shutdown via client.closeAllSessions() or client.close() (the latter when code mode / E2B requires it).
  • Do not call both cleanup paths for the same ownership scope unless current docs or local runtime prove it is necessary.
  • Serverless with tracing → await agent.flush() before cleanup.

Reference routing

Load only what the current task needs.

Scripts

Scripts live in scripts/ beside this skill. Use --help first when the task is unclear.

Final checks

• SKILL.md stays lean and routes every reference file.
• Frontmatter description starts with Use if and is 100 characters or fewer.
• No stale hard-coded mcp-use version claims remain.
• Node runtime guidance matches the latest npm engines result.
• Provider/model claims follow the verification policy instead of dated catalogs.
• Cleanup examples follow the ownership policy above.
• Validation passes with python3 scripts/validate-skills.py.