Install & Compatibility
Where this runs
tested against v1.7.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
137MB installed
● package 137MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Agent
✓ from mcp_use import Agent
Client
✓ from mcp_use import Client
Server
✓ from mcp_use import Server
Channel
✓ from mcp_use import Channel
This quickstart demonstrates how to set up a basic MCP Agent and a Client using `mcp-use`. The Agent defines a message handler, the Client connects to it, and they communicate via a named Channel. It showcases the core asynchronous nature and connection management.
import asyncio
from mcp_use import Agent, Client, Server, Channel
async def main():
# Example: A simple MCP Agent and Client interaction
# 1. Start a simple Agent
class MyAgent(Agent):
async def handle_message(self, message: str) -> str:
print(f"Agent received: {message}")
return f"Agent processed: {message.upper()}"
agent = MyAgent(name="test-agent", host="127.0.0.1", port=8000)
agent_task = asyncio.create_task(agent.start())
await asyncio.sleep(0.5) # Give agent time to start
# 2. Connect a Client to the Agent
client = Client(name="test-client", host="127.0.0.1", port=8000)
await client.connect()
# 3. Send a message via a Channel
try:
async with client.channel("my-channel") as channel:
response = await channel.send("hello mcp!")
print(f"Client received: {response}")
assert response == "Agent processed: HELLO MCP!"
finally:
# 4. Clean up
await client.disconnect()
agent_task.cancel()
await agent.stop()
print("Cleanup complete.")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingmcp-use requires Python 3.11 or newer. Attempting to install or run on older Python versions (e.g., 3.10, 3.9) will result in syntax errors, dependency resolution failures, or runtime exceptions due to modern language features and type hints used throughout the library.fixUpgrade your Python environment to 3.11 or higher. Consider using `pyenv` or `conda` for managing multiple Python versions.
affects: <1.0.0 (implicitly, as 3.11+ is a hard requirement from initial stable releases)
gotchaAll core operations in mcp-use (e.g., `Agent.start()`, `Client.connect()`, `Channel.send()`) are `async` functions and must be `await`ed within an `asyncio` event loop. Forgetting `await` or trying to call them synchronously will lead to `RuntimeWarning: coroutine '...' was never awaited` or `TypeError`.fixEnsure all calls to mcp-use functions marked `async def` are preceded by `await` and executed within an `asyncio.run()` block or an existing event loop. Always use `asyncio.run(main())` for top-level asynchronous execution.
affects: All versions
gotchaImproper resource cleanup (e.g., not disconnecting clients, stopping agents, or closing channels) can lead to resource leaks, open network connections, and processes that don't terminate cleanly. This is particularly critical in long-running services or tests.fixAlways use `async with client.channel(...)` for channels to ensure automatic closing. Explicitly call `await client.disconnect()` and `await agent.stop()` in `finally` blocks or during application shutdown to release resources.
affects: All versions
gotchaError handling across distributed components (Agent, Client, Server) requires careful consideration. Uncaught exceptions on one side might silently fail or lead to connection drops without clear indication on the other.fixImplement robust `try...except` blocks around `send` and `handle_message` calls. Utilize `mcp-use`'s error reporting mechanisms (if any) and structured logging to trace issues across your distributed system.
affects: All versions
Upgrade
Version history
1.7.0latest on PyPI · released Mar 17, 2026
Audit
Dependencies
Python 3.11+requiredThe library heavily utilizes modern Python features (e.g., `asyncio`, `typing`) introduced or significantly improved in Python 3.11 and later.