{"id":5314,"library":"mcp-use","title":"MCP Use Framework","description":"mcp-use is a full-stack Python framework for building Multi-Cloud Platform (MCP) agents, clients, and servers. It simplifies the development of distributed systems with a focus on asynchronous communication. The current version is 1.7.0 and it maintains an active release cadence, frequently adding features and improvements.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/mcp-use/mcp-use","tags":["asyncio","framework","distributed-systems","agent","client","server","network"],"install":[{"cmd":"pip install mcp-use","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"The library heavily utilizes modern Python features (e.g., `asyncio`, `typing`) introduced or significantly improved in Python 3.11 and later.","package":"Python 3.11+","optional":false}],"imports":[{"symbol":"Agent","correct":"from mcp_use import Agent"},{"symbol":"Client","correct":"from mcp_use import Client"},{"symbol":"Server","correct":"from mcp_use import Server"},{"symbol":"Channel","correct":"from mcp_use import Channel"}],"quickstart":{"code":"import asyncio\nfrom mcp_use import Agent, Client, Server, Channel\n\nasync def main():\n    # Example: A simple MCP Agent and Client interaction\n\n    # 1. Start a simple Agent\n    class MyAgent(Agent):\n        async def handle_message(self, message: str) -> str:\n            print(f\"Agent received: {message}\")\n            return f\"Agent processed: {message.upper()}\"\n\n    agent = MyAgent(name=\"test-agent\", host=\"127.0.0.1\", port=8000)\n    agent_task = asyncio.create_task(agent.start())\n\n    await asyncio.sleep(0.5) # Give agent time to start\n\n    # 2. Connect a Client to the Agent\n    client = Client(name=\"test-client\", host=\"127.0.0.1\", port=8000)\n    await client.connect()\n\n    # 3. Send a message via a Channel\n    try:\n        async with client.channel(\"my-channel\") as channel:\n            response = await channel.send(\"hello mcp!\")\n            print(f\"Client received: {response}\")\n\n            assert response == \"Agent processed: HELLO MCP!\"\n\n    finally:\n        # 4. Clean up\n        await client.disconnect()\n        agent_task.cancel()\n        await agent.stop()\n        print(\"Cleanup complete.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.11 or higher. Consider using `pyenv` or `conda` for managing multiple Python versions.","message":"mcp-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.","severity":"breaking","affected_versions":"<1.0.0 (implicitly, as 3.11+ is a hard requirement from initial stable releases)"},{"fix":"Ensure 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.","message":"All 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always 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.","message":"Improper 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement 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.","message":"Error 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}