mcp-use MCP — 사용 사례, 설치 & 라이브 데모

Name: mcp-use MCP Server
Author: mcp-use

왜 쓰나요

핵심 기능

Connect multiple MCP servers from one Python process
Works with any LangChain chat model (OpenAI, Anthropic, local, OSS)
Direct-call mode — invoke tools without paying an LLM tax
Streamable-HTTP transport supported for remote servers

라이브 데모

실제 사용 모습

mcp-use.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-use": {
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-use": {
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-use": {
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-use": {
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-use",
      "command": "uvx",
      "args": [
        "mcp-use"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-use": {
      "command": {
        "path": "uvx",
        "args": [
          "mcp-use"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mcp-use -- uvx mcp-use

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: mcp-use

Build a custom agent that uses playwright + filesystem + postgres

👤 Python devs building vertical agents ⏱ ~45 min intermediate

언제 쓸까: You need a repeatable automation (not Claude Desktop) that chains browser + files + DB.

사전 조건

Python 3.10+, uv or pip — Standard setup
An LLM API key (OpenAI / Anthropic) — Set as env var your LangChain model expects

흐름

Define the server configs

Write a mcp-use config that connects to playwright (stdio via npx), postgres (stdio via uvx), and filesystem (local path scoped).✓ 복사됨

→ JSON/dict config matching the schema
Wire the agent

Create an MCPAgent using ChatAnthropic (claude-sonnet-4) and the config above. Max iterations = 15.✓ 복사됨

→ Agent instance ready to .run()
Run a task

Run: 'Crawl docs.example.com, save each page to ./knowledge/, then index titles into the postgres docs table.' Observe tool calls in logs.✓ 복사됨

→ Task completes, data lands where expected

결과: A scriptable agent you can schedule, deploy, or embed — not tied to a desktop client.

함정

Agent loops between servers, burning tokens — Set strict max_iterations and use an LLM that follows instructions well — GPT-4o-mini often loops on complex chains, use a stronger model
stdio servers zombied after crash — Always use the async context manager pattern — it handles cleanup; don't manage the process yourself

함께 쓰기: fastmcp · mcp-agent

Call MCP tools from Python without an LLM

👤 Engineers automating ops tasks ⏱ ~20 min intermediate

언제 쓸까: You want to invoke an MCP tool as part of a larger Python pipeline, deterministically.

흐름

Connect the client directly

Use MCPClient to connect to my filesystem MCP. List available tools.✓ 복사됨

→ Tool names + schemas printed
Call a tool with typed args

Call write_file with path='./out.txt' and content='hello'. Confirm the return value.✓ 복사됨

→ File written, no LLM involved
Chain into your business logic

Wrap this in a function save_report(df) that calls the MCP tool — integrate into my existing Python ETL.✓ 복사됨

→ Reusable function

결과: MCP-as-library: same servers used by Claude Desktop also callable from plain Python.

함정

Errors don't bubble up naturally — MCP errors come as result objects with isError: true — Check result.isError after every call; don't assume success

Build a router agent that picks the right MCP for each request

👤 Teams shipping agent products ⏱ ~60 min advanced

언제 쓸까: Users send mixed requests (code, data, web) — one monolithic prompt with 50 tools degrades; you want routing.

흐름

Define server groups

Split my MCP servers into 3 groups: 'code' (git, github), 'data' (postgres, bigquery), 'web' (firecrawl, playwright).✓ 복사됨

→ 3 separate agent configs
Add a router layer

Write a classifier prompt that picks one group based on the user's intent. Use it to instantiate the matching MCPAgent on demand.✓ 복사됨

→ Classifier returns one of {code, data, web}
Test with mixed traffic

Run 10 varied requests through the router. Log which group handled each and whether the answer was correct.✓ 복사됨

→ Accuracy table + latency stats

결과: A modular agent system where each request only sees the tools relevant to it — better accuracy, lower token cost.

함정

Edge cases where the request needs two groups (e.g., 'scrape + save to DB') — Define a fourth 'cross' group or fall back to the Orchestrator pattern via mcp-agent

함께 쓰기: mcp-agent

조합

다른 MCP와 조합해 10배 효율

mcp-use + mcp-agent

Use mcp-use for connecting servers, mcp-agent for workflow patterns (orchestrator/evaluator)

Build an evaluator-optimizer loop where a writer agent uses mcp-use to access filesystem + git, and a critic agent reviews output using the same servers.✓ 복사됨

mcp-use + fastmcp

Write a server with FastMCP, then script against it with mcp-use — end-to-end Python agent stack

Server: expose our pricing API via FastMCP. Client: use mcp-use to call it in a pricing-simulation script.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
MCPClient(config)	server config dict/path	Entry point for any mcp-use script	free
MCPAgent(llm, client, max_steps)	LangChain chat model + MCPClient	When you want LLM-driven tool selection	LLM calls only
client.list_tools()	server_name?	Introspect what's available before calling	free
client.call_tool(name, args)	tool_name, dict	Direct deterministic invocation — no LLM	depends on tool
MCPServer decorator API	@server.tool() on functions	Less common; FastMCP is usually cleaner for server-building	free

비용 및 제한

운영 비용

API 쿼터: None from mcp-use itself; depends on LLM and downstream MCPs
호출당 토큰: LLM-driven calls burn tokens — the usual LangChain agent cost model
금액: Library is free, LLM usage is not
팁: For deterministic flows, use client.call_tool directly — skip the LLM. Reserve MCPAgent for genuinely ambiguous tasks.

보안

권한, 시크릿, 파급범위

자격 증명 저장: Per underlying MCP — mcp-use doesn't add a layer

데이터 외부 송신: LLM provider + every connected MCP

문제 해결

자주 발생하는 오류와 해결

ConnectionError when starting stdio server

The command in your config isn't on PATH or the package isn't installed. Test manually: run the same npx -y ... in a terminal first.

확인: which npx && npx -y @modelcontextprotocol/server-filesystem --help

Agent calls tools correctly but answer is wrong

Usually an LLM issue — try a stronger model. GPT-4o-mini and open-source 7B models often misinterpret tool results.

Event loop already running error

You're calling a sync API from within an async context. Use await and the async client methods throughout.

Tools from server A shadow names in server B

Prefix tool names per server in your config, or rely on the library's built-in namespace handling (set namespace=True).

대안

mcp-use 다른 것과 비교

대안	언제 쓰나	단점/장점
mcp-agent	You want workflow patterns (orchestrator, router, evaluator) baked in	More opinionated; less flexible if you want raw LangChain
Official Python MCP SDK	You want the lowest-level client — no LangChain, no abstractions	More plumbing code
LangGraph + MCP	You need stateful multi-turn graphs with checkpoints	Steeper learning curve; overkill for simple agents

mcp-use