mcp-agent

Abstracts OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, and Google AI behind a unified AugmentedLLM interface that normalizes tool-calling schemas, token tracking, and cost management across providers. Uses provider-specific adapters to translate between native function-calling formats (OpenAI's tools array, Anthropic's tool_use blocks) into a canonical internal representation, enabling seamless model swapping without workflow changes.

Manages the full lifecycle of Model Context Protocol servers (startup, connection, tool discovery, shutdown) across three transport mechanisms: STDIO, Server-Sent Events (SSE), and WebSocket. The MCPApp container automatically initializes MCP connections, discovers available tools/resources, and handles connection pooling and error recovery without requiring manual transport configuration in agent code.

Provides a framework for building MCP servers that expose tools and resources to agents. Developers define tools as Python functions with type hints, and the framework automatically generates MCP tool schemas and handles tool invocation. Supports both simple function-based tools and complex stateful tools with initialization. Resources can expose file contents, API responses, or other data to agents.

Enables workflows to pass context and state between agents through a shared execution context. Each workflow step can access outputs from previous steps, and agents can read/write to a shared state dictionary. The WorkflowExecutionSystem manages context isolation between concurrent workflows to prevent state leakage, using Python context variables to maintain execution context across async boundaries.

Implements a Router workflow pattern that classifies incoming tasks by intent and routes them to specialized agents. Uses an LLM to classify the task intent, then selects the appropriate agent from a configured set based on the classification. Enables building systems where different agents handle different types of tasks (e.g., research agent, analysis agent, writing agent) without requiring explicit routing logic.

Implements an Evaluator-Optimizer workflow pattern where an evaluator agent assesses the quality of a worker agent's output against specified criteria, and an optimizer agent refines the output based on evaluation feedback. Enables building self-improving agent systems that iteratively refine outputs until quality criteria are met, with configurable iteration limits and evaluation metrics.

Provides six pre-built workflow patterns (Orchestrator, Deep Orchestrator, Parallel, Router, Evaluator-Optimizer, Swarm) that define how agents interact with tools and each other. Each pattern is implemented as a composable execution engine that handles agent sequencing, tool invocation, result aggregation, and error handling. Workflows are defined declaratively in YAML/Python and executed by the WorkflowExecutionSystem which manages state, context passing, and tool result routing.

Provides a YAML-based configuration system (MCPApp) that declaratively defines agents, MCP servers, LLM providers, and workflows. Supports environment variable substitution, secret management via .env files, and schema validation against a JSON schema. Configuration is loaded at application startup and validated before any agents execute, catching configuration errors early without runtime failures.

Automatically tracks input/output tokens and calculates costs for every LLM invocation across all providers (OpenAI, Anthropic, Azure, Bedrock, Google). Uses provider-specific pricing models and tokenizer implementations to compute per-call costs, aggregates costs across workflow execution, and exposes token metrics via the event system. Integrates with observability pipeline to enable cost analysis and budget monitoring.

Implements a comprehensive event system that emits structured events for every significant operation (agent execution, tool invocation, LLM calls, workflow transitions). Events are captured by pluggable exporters (file-based, OpenTelemetry) and can be analyzed via event analysis tools. Tracing is isolated per workflow execution to prevent cross-contamination in concurrent scenarios, using context variables to maintain execution context across async boundaries.

Implements a permission model where each Agent is explicitly granted access to specific MCP servers and tools. The Agent class maintains a list of allowed servers, and tool invocation is gated by checking if the requested tool belongs to an allowed server. This enables fine-grained access control in multi-agent systems where different agents have different tool permissions, preventing unauthorized tool access.

Enables agents to generate structured outputs (JSON, Pydantic models) by providing a schema to the LLM and validating the response against that schema. Uses provider-specific structured output features (OpenAI's JSON mode, Anthropic's tool_use) when available, with fallback to post-processing validation. Automatically retries with corrected prompts if validation fails, up to a configurable number of attempts.

Provides a mechanism for agents to pause execution and request human approval before executing sensitive operations (e.g., deleting files, making external API calls). Agents can emit approval requests with context (what action, why, what are the consequences), and workflows pause until a human provides approval or rejection. Integrates with the event system to notify external systems (Slack, email) of pending approvals.

Built on Python's asyncio, mcp-agent enables concurrent execution of multiple agents and tools within a single workflow. The Parallel workflow pattern executes multiple agents concurrently and aggregates results, while individual tool invocations are non-blocking. Uses async context managers for resource management and ensures proper cleanup of MCP connections even if agents fail.