MCP Agent
Author: lastmile-ai
Description: A Python framework/SDK for building AI agents on the Model Context Protocol (MCP). Provides full MCP client support (tools/resources/prompts/notifications + advanced features like OAuth, sampling, elicitation, roots), composable “Building Effective Agents” workflow patterns (map-reduce/parallel, router, intent classifier, orchestrator-workers, deep research, evaluator-optimizer, swarm), and optional durable execution via Temporal. Includes a CLI (run via `uvx mcp-agent`) to scaffold projects, manage secrets, inspect workflows, and deploy apps as MCP servers (stdio/HTTPS via cloud). Installation: `uv add "mcp-agent"` or `pip install mcp-agent`; optional LLM extras like `mcp-agent[openai,anthropic,google,azure,bedrock]`. Example MCP server dependencies commonly used: `mcp-server-fetch` (via `uvx`) and `@modelcontextprotocol/server-filesystem` (via `npx`).
Stars: 8.1k
Forks: 807
License: Apache License 2.0
Category: Open Source
Overview
Installation
uv add "mcp-agent"pip install mcp-agentuv add "mcp-agent[openai, anthropic, google, azure, bedrock]"mkdir hello-mcp-agent && cd hello-mcp-agent
uvx mcp-agent init
uv init
uv add "mcp-agent[openai]"
# Add openai API key to `mcp_agent.secrets.yaml` or set `OPENAI_API_KEY`
uv run main.pycd examples/basic/mcp_basic_agent # Or any other example
# Option A: secrets YAML
# cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml && edit mcp_agent.secrets.yaml
uv run main.pyFAQs
What are the most common challenges faced when configuring an MCP server?
Common MCP server configuration challenges include missing Python dependencies causing installation failures, backward incompatibilities from library version mismatches, and executables absent from PATH blocking startup. Platform-specific failures occur across OS architectures, and deployment packaging errors create ModuleNotFoundError issues. Security risks include OAuth misconfigurations with localhost defaults in production and credential mismanagement requiring secrets managers.
What are the key security features of an MCP server?
MCP servers implement permission-based access control requiring explicit user approval for sensitive operations, TLS 1.3 transport encryption with mutual authentication, OAuth 2.1 token-based auth, and process isolation through sandboxed environments. Additional protections include JSON Schema input validation, immutable audit logging, rate limiting per client, and cryptographically signed server discovery metadata to prevent man-in-the-middle attacks and unauthorized tool execution.
How can I optimize the performance of an MCP server?
Optimize MCP server performance by shifting computation server-side using specialized models instead of general-purpose LLMs, reducing token usage by sixty-five percent and latency by thirty-eight percent. Implement disk-based vector storage like DiskANN to maintain constant memory as datasets scale. Apply aggressive caching with multi-region Redis, batch requests, and use connection pooling for throughput gains.
How do I switch an MCP Agent project from asyncio to Temporal for durable execution, and what changes are needed in the codebase?
Switching requires installing the Temporal extra via `uv add "mcp-agent[temporal]"`, configuring a Temporal server connection, and changing the runtime mode in your project configuration. The decorator syntax remains identical because MCP Agent maintains API compatibility across both execution modes. You'll need to ensure your workflow functions are deterministic and avoid non-deterministic operations like random number generation or direct I/O within workflow definitions.
Can MCP Agent workflows nest multiple patterns together, such as a router inside an orchestrator, and what does that look like in code?
Yes, patterns nest because each is an AugmentedLLM that accepts other AugmentedLLMs as inputs. In code, pass a router created via `create_router_llm` as a worker agent to `create_orchestrator`. The orchestrator treats the router as a callable agent, letting it delegate subtasks to the router's downstream specialists without additional wrappers or adapters.
How does MCP Agent's human-in-the-loop feature work with the __human_input__ tool, and can it be customized for approval workflows?
MCP Agent's human-in-the-loop uses `request_human_input` to pause workflow execution, exposing `__human_input__` as a callable tool that agents invoke when decisions require approval. Customization happens through standard Python control flow: wrap approval calls with conditional logic, implement custom validation functions, or chain multiple approval stages by nesting `request_human_input` calls within orchestrator patterns before resuming execution.