---
title: "Core Orchestration & Execution"
description: "Central orchestration and execution engine for the mcp-agent framework"
---

```mermaid
graph LR
    MCPApp["MCPApp"]
    Settings["Settings"]
    Executor["Executor"]
    AsyncioExecutor["AsyncioExecutor"]
    TemporalExecutor["TemporalExecutor"]
    Workflow["Workflow"]
    WorkflowRegistry["WorkflowRegistry"]
    BaseSignalHandler["BaseSignalHandler"]
    TemporalExecutorConfig["TemporalExecutorConfig"]
    InteractiveWorkflow["InteractiveWorkflow"]

    MCPApp -- "initializes and depends on" --> Settings
    MCPApp -- "orchestrates and utilizes" --> Executor
    MCPApp -- "manages and queries" --> WorkflowRegistry
    Settings -- "provides configuration to" --> MCPApp
    Settings -- "provides configuration to" --> TemporalExecutorConfig
    Executor -- "executes" --> Workflow
    AsyncioExecutor -- "implements" --> Executor
    TemporalExecutor -- "implements" --> Executor
    AsyncioExecutor -- "executes" --> Workflow
    TemporalExecutor -- "utilizes" --> TemporalExecutorConfig
    Workflow -- "interacts with" --> BaseSignalHandler
    WorkflowRegistry -- "stores and provides access to" --> Workflow
    TemporalExecutorConfig -- "configures" --> TemporalExecutor
    TemporalExecutorConfig -- "depends on" --> Settings
    InteractiveWorkflow -- "extends" --> Workflow
```

<Info>
This documentation was generated by [CodeBoarding](https://github.com/CodeBoarding/GeneratedOnBoardings) to provide comprehensive insights into the core orchestration and execution layer.
</Info>

## Overview

The Core Orchestration & Execution component is the central nervous system of the mcp-agent application, responsible for managing the overall application lifecycle, loading global configurations, and orchestrating the execution of tasks and complex workflows. It supports both asynchronous and durable execution models, ensuring robust workflow state management and enabling sophisticated agentic behaviors.

## Key Components

### MCPApp

The primary application orchestrator and entry point. It is responsible for bootstrapping the application, loading global configurations (Settings), and coordinating the various sub-systems. It manages the lifecycle of the application and delegates the execution of workflows to appropriate executors.

**Key Features:**
- Application lifecycle management
- Global configuration loading
- Sub-system coordination
- Workflow execution delegation

### Settings

This component is responsible for managing and providing access to global application configurations. It loads settings from various sources, making them available to other components that require specific parameters for their operation (e.g., executor configurations, external service credentials).

**Key Features:**
- Configuration management
- Multi-source settings loading
- Parameter distribution
- Environment-specific configurations

### Executor

This is the abstract interface for executing workflows and tasks within the mcp-agent framework. It defines the contract for how executable units are run, allowing for different concrete implementations to handle various execution environments, such as in-process asynchronous execution or durable execution via Temporal.io.

**Implementation Details:**
- [View Source](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/executor/executor.py#L52-L239)

### AsyncioExecutor

A concrete implementation of the Executor interface that handles asynchronous, in-process execution of workflows. It leverages Python's asyncio capabilities for concurrent task management, suitable for short-lived or non-durable workflows.

**Key Features:**
- Asynchronous execution
- In-process task management
- Concurrent workflow handling
- Suitable for short-lived workflows

### TemporalExecutor

A concrete implementation of the Executor interface that provides durable and fault-tolerant workflow execution using the Temporal.io platform. It ensures workflow state persistence, retries, and recovery, critical for long-running or mission-critical agentic processes.

**Key Features:**
- Durable execution
- Fault tolerance
- State persistence
- Automatic retries and recovery
- Long-running workflow support

### Workflow

This serves as the foundational abstraction for defining executable units of work or complex agentic processes. It encapsulates the logic, state, and potential interactions of a workflow, which is then managed and executed by an Executor.

**Implementation Details:**
- [View Source](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/executor/workflow.py#L71-L528)

### WorkflowRegistry

This component is responsible for managing the registration and retrieval of workflow definitions. It acts as a central catalog, making workflows discoverable and available for execution by the system, supporting both in-memory and Temporal-backed storage.

**Implementation Details:**
- [View Source](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/executor/workflow_registry.py#L19-L146)

**Key Features:**
- Workflow registration
- Central catalog management
- Discovery and retrieval
- Multiple storage backends

### BaseSignalHandler

This component provides the abstract mechanism for handling signals within workflows. Signals are crucial for inter-workflow communication, managing workflow state, and enabling external interactions, which are vital for robust and responsive execution in asynchronous and durable environments.

**Key Features:**
- Signal handling abstraction
- Inter-workflow communication
- State management
- External interaction support

### TemporalExecutorConfig

Defines the specific configuration parameters required for the TemporalExecutor to operate. This includes connection details for the Temporal server and other execution-specific settings, ensuring proper integration with the durable execution backend.

**Key Features:**
- Temporal server configuration
- Connection management
- Execution-specific settings
- Backend integration

### InteractiveWorkflow

A specialized type of Workflow designed to handle human interaction. This component is crucial for agentic systems that require user input or approval at various stages of a workflow, enabling human-in-the-loop processes and complex decision flows.

**Implementation Details:**
- [View Source](https://github.com/lastmile-ai/mcp-agent/blob/main/src/mcp_agent/executor/temporal/interactive_workflow.py#L20-L83)

**Key Features:**
- Human interaction support
- User input handling
- Approval workflows
- Human-in-the-loop processes
