mcp-use MCP — Casos de uso, Instalar & Demo ao vivo

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

Por que usar

Principais recursos

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

Demo ao vivo

Como fica na prática

mcp-use.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

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

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

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

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

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

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

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

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

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

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

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

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

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

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: mcp-use

Build a custom agent that uses playwright + filesystem + postgres

👤 Python devs building vertical agents ⏱ ~45 min intermediate

Quando usar: You need a repeatable automation (not Claude Desktop) that chains browser + files + DB.

Pré-requisitos

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

Fluxo

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).✓ Copiado

→ JSON/dict config matching the schema
Wire the agent

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

→ 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.✓ Copiado

→ Task completes, data lands where expected

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

Armadilhas

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

Combine com: fastmcp · mcp-agent

Call MCP tools from Python without an LLM

👤 Engineers automating ops tasks ⏱ ~20 min intermediate

Quando usar: You want to invoke an MCP tool as part of a larger Python pipeline, deterministically.

Fluxo

Connect the client directly

Use MCPClient to connect to my filesystem MCP. List available tools.✓ Copiado

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

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

→ 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.✓ Copiado

→ Reusable function

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

Armadilhas

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

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

Fluxo

Define server groups

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

→ 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.✓ Copiado

→ 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.✓ Copiado

→ Accuracy table + latency stats

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

Armadilhas

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

Combine com: mcp-agent

Combinações

Combine com outros MCPs para 10× de alavancagem

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.✓ Copiado

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.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
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

Custo e limites

O que custa rodar

Cota de API: None from mcp-use itself; depends on LLM and downstream MCPs
Tokens por chamada: LLM-driven calls burn tokens — the usual LangChain agent cost model
Monetário: Library is free, LLM usage is not
Dica: For deterministic flows, use client.call_tool directly — skip the LLM. Reserve MCPAgent for genuinely ambiguous tasks.

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Per underlying MCP — mcp-use doesn't add a layer

Saída de dados: LLM provider + every connected MCP

Solução de problemas

Erros comuns e correções

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.

Verificar: 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).

Alternativas

mcp-use vs. outros

Alternativa	Quando usar	Troca
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

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills