Updates to ----

    MCP Agent SDK
    ----
    * Overview
    * Core Components
        * Configuring your application
        * Specify secrets
        * MCPApp
        * Agents
        * AugmentedLLM
        * Connecting to MCP servers (MCP server registry, MCP connection manager, just some examples)
        * Execution engine
        * Workflows

Author: saqadri

docs/docs.json

@@ -1,6 +1,10 @@
 {
   "$schema": "https://mintlify.com/docs.json",
   "name": "mcp-agent",
+  "logo": {
+    "light": "/logo/mcp-agent.png",
+    "dark": "/logo/mcp-agent.png"
+  },
   "theme": "willow",
   "colors": {
     "primary": "#3B82F6",

docs/mcp-agent-sdk/core-components/configuring-your-application.mdx

@@ -7,20 +7,22 @@ icon: gear
 
 mcp-agent uses YAML configuration files to manage application settings, MCP servers, and model providers.
 
-## Configuration Files
+## Configuration files
 
-mcp-agent uses two configuration files:
+Start with two YAML files at the root of your project:
 
 <CardGroup cols={2}>
   <Card title="mcp_agent.config.yaml" icon="gear">
-    Application configuration, MCP servers, and non-sensitive settings
+    Application configuration, MCP servers, logging, execution engine, model defaults
   </Card>
   <Card title="mcp_agent.secrets.yaml" icon="key">
-    API keys, secrets, and sensitive credentials (gitignored)
+    API keys, OAuth credentials, and other secrets (gitignored)
   </Card>
 </CardGroup>
 
-## Basic Configuration
+See [Specify Secrets](/mcp-agent-sdk/core-components/specify-secrets) for credential management patterns and production tips.
+
+## Basic configuration
 
 Here's a minimal configuration:
 
@@ -138,7 +140,7 @@ mcp:
 
 ## Model Providers
 
-Configure your LLM provider:
+Configure your LLM provider. Many examples follow this layout—for instance, the [basic finder agent](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_basic_agent) sets OpenAI defaults exactly this way.
 
 <Tabs>
   <Tab title="OpenAI">
@@ -198,6 +200,68 @@ Configure your LLM provider:
   </Tab>
 </Tabs>
 
+## OAuth configuration
+
+Two places control OAuth behaviour:
+
+1. **Global OAuth settings (`settings.oauth`)** configure token storage and callback behaviour (loopback ports, preload timeouts, Redis support).
+2. **Per-server auth (`mcp.servers[].auth.oauth`)** specifies client credentials, scopes, and provider overrides.
+
+```yaml mcp_agent.config.yaml
+oauth:
+  token_store:
+    backend: redis
+    redis_url: ${OAUTH_REDIS_URL}
+
+mcp:
+  servers:
+    github:
+      command: "uvx"
+      args: ["mcp-server-github"]
+      auth:
+        oauth:
+          enabled: true
+          client_id: ${GITHUB_CLIENT_ID}
+          client_secret: ${GITHUB_CLIENT_SECRET}
+          redirect_uri_options:
+            - "http://127.0.0.1:33418/callback"
+          include_resource_parameter: false
+```
+
+Pair this with secrets in `mcp_agent.secrets.yaml` or environment variables. For concrete walkthroughs, study the [OAuth basic agent](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent) and the [interactive OAuth tool](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/interactive_tool). The [pre-authorize workflow example](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) shows how to seed credentials before a background workflow runs.
+
+## Programmatic configuration
+
+You can bypass file discovery by passing a fully-formed `Settings` object (or a path) to `MCPApp`. This is especially useful for tests and scripts that compose configuration dynamically.
+
+```python
+from mcp_agent.app import MCPApp
+from mcp_agent.config import Settings, OpenAISettings
+
+settings = Settings(
+    execution_engine="asyncio",
+    openai=OpenAISettings(
+        default_model="gpt-4o-mini",
+        temperature=0.3,
+    ),
+)
+
+app = MCPApp(name="dynamic", settings=settings)
+```
+
+Because `Settings` extends `BaseSettings`, environment variables still override any fields you set explicitly.
+
+## Configuration discovery
+
+When `MCPApp` starts, it resolves settings in this order:
+- `MCP_APP_SETTINGS_PRELOAD` / `MCP_APP_SETTINGS_PRELOAD_STRICT`
+- Explicit `settings` argument passed to `MCPApp`
+- `mcp_agent.config.yaml` (or `mcp-agent.config.yaml`) discovered in the working directory, parent directories, `.mcp-agent/` folders, or `~/.mcp-agent/`
+- `mcp_agent.secrets.yaml` / `mcp-agent.secrets.yaml` merged on top
+- Environment variables (including values from `.env`, using `__` for nesting)
+
+Environment variables override file-based values, while the preload option short-circuits everything else—handy for containerised deployments that mount secrets from a vault. [Specify Secrets](/mcp-agent-sdk/core-components/specify-secrets) covers strategies for each stage.
+
 ## Environment Variables
 
 You can reference environment variables in configuration:

docs/mcp-agent-sdk/core-components/connecting-to-mcp-servers.mdx

@@ -5,17 +5,141 @@ description: "Learn how to connect to MCP servers using the MCP server registry
 icon: plug
 ---
 
-<Info>
-Content to be migrated covering MCP server registry, MCP connection manager, gen_client, connect/disconnect patterns.
-</Info>
-
 ## Overview
 
-mcp-agent provides multiple ways to connect to and manage MCP servers:
+Every `MCPApp` initialises a `ServerRegistry` that knows how to start and authenticate each server defined in `mcp_agent.config.yaml`. The registry works hand in hand with `MCPConnectionManager` to provide two patterns:
+
+- Short-lived connections using `gen_client`, perfect for one-off operations.
+- Persistent connections managed by the connection manager, ideal for agents and long-running workflows.
+
+Understanding these two layers lets you control connection reuse, lifecycle, and error handling with precision.
+
+## Inspect configured servers
+
+After `app.run()` the registry is accessible via the context:
+
+```python
+async with app.run() as running_app:
+    registry = running_app.server_registry
+    for name, cfg in registry.registry.items():
+        running_app.logger.info(
+            "Server configured",
+            data={"name": name, "transport": cfg.transport},
+        )
+```
+
+The registry resolves transports (`stdio`, `sse`, `streamable_http`, `websocket`), applies authentication (`api_key` or OAuth), and exposes helpers such as `register_init_hook`.
+
+## Ephemeral sessions with `gen_client`
+
+Use `gen_client` when you need a connection for the duration of a `with` block. It spins up the server process (for stdio transports), performs initialisation, yields an `MCPAgentClientSession`, and tears everything down automatically—a handy pattern for scripts, CLI utilities, or inspection. The [basic finder agent](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_basic_agent) uses the same underlying helpers when it initialises an agent.
+
+```python
+from mcp_agent.mcp.gen_client import gen_client
+
+async with app.run():
+    async with gen_client(
+        server_name="fetch",
+        server_registry=app.server_registry,
+        context=app.context,
+    ) as session:
+        tools = await session.list_tools()
+        print("Fetch tools:", [tool.name for tool in tools.tools])
+```
+
+This is the simplest way to script against MCP servers without committing to persistent connections.
+
+## Persistent connections and connection pooling
+
+The `ServerRegistry` owns a `MCPConnectionManager` (`registry.connection_manager`) that maintains long-lived connections in a background task group. You can either interact with it directly or rely on helpers such as `mcp_agent.mcp.gen_client.connect`.
+
+```python
+from mcp_agent.mcp.gen_client import connect, disconnect
+
+async with app.run():
+    session = await connect("filesystem", app.server_registry, context=app.context)
+    try:
+        result = await session.list_resources()
+        print("Roots:", [r.uri for r in result.resources])
+    finally:
+        await disconnect("filesystem", app.server_registry)
+```
+
+When you need multiple connections simultaneously, open the manager as a context manager to ensure orderly shutdown:
+
+```python
+async with app.run():
+    async with app.server_registry.connection_manager as manager:
+        fetch_conn = await manager.get_server("fetch")
+        filesystem_conn = await manager.get_server("filesystem")
+        await fetch_conn.session.list_tools()
+        await filesystem_conn.session.list_tools()
+    # Connections are closed when the block exits
+```
+
+## Connection persistence in agents
+
+Agents use the connection manager behind the scenes. Set `connection_persistence=True` (the default) to keep servers warm between tool calls or `False` to close the transport after each request.
+
+```python
+agent = Agent(
+    name="finder",
+    instruction="Use fetch and filesystem tools",
+    server_names=["fetch", "filesystem"],
+    connection_persistence=True,
+    context=app.context,
+)
+```
+
+Persistent connections dramatically reduce latency when calling the same server repeatedly.
+
+## Aggregating multiple servers
+
+`MCPAggregator` builds a “server-of-servers” using the same registry and connection manager. You can namespace tool calls or expose a merged surface area:
+
+```python
+from mcp_agent.mcp.mcp_aggregator import MCPAggregator
+
+async with app.run():
+    async with MCPAggregator.create(
+        server_names=["fetch", "filesystem"],
+        connection_persistence=True,
+        context=app.context,
+    ) as aggregator:
+        await aggregator.list_tools()                # Combined tool view
+        await aggregator.call_tool("fetch_fetch", {"url": "https://example.com"})
+        await aggregator.call_tool("read_text_file", {"path": "README.md"})
+```
+
+This pattern mirrors the [`examples/basic/mcp_server_aggregator`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/mcp_server_aggregator) sample and is commonly used when turning an entire app into a single MCP server.
+
+## OAuth-aware connections
+
+When server definitions include `auth.oauth`, the registry and connection manager automatically coordinate with the app’s token manager. The OAuth examples highlight three recurring patterns:
+
+- [`examples/basic/oauth_basic_agent`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/basic/oauth_basic_agent) – an agent maintains persistent connections to the GitHub MCP server using the client-only loopback flow.
+- [`examples/oauth/interactive_tool`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/interactive_tool) – a client opens a temporary `gen_client` session, receives an `auth/request`, and walks through the browser login.
+- [`examples/oauth/pre_authorize`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) – tokens are seeded before an asynchronous workflow runs so the background execution never needs interactive auth.
+
+In each case, you get the same `ClientSession` interface; the difference lies in how tokens are acquired and stored.
+
+## Initialisation hooks and authentication
+
+You can register custom logic that runs immediately after a server initialises. It is perfect for seeding credentials, warming caches, or performing health checks.
+
+```python
+def after_start(session, auth):
+    session.logger.info("Server ready", data={"auth": bool(auth)})
+
+app.server_registry.register_init_hook("fetch", after_start)
+```
+
+When a server declares OAuth configuration (`mcp.servers[].auth.oauth`), `MCPApp` automatically injects an `OAuthHttpxAuth` handler so `MCPConnectionManager` can obtain and refresh tokens using the shared `TokenManager`. This means you do not need to ship long-lived access tokens in your config.
+
+## Error handling & retries
 
-- **MCP Server Registry** - Central registry of configured servers
-- **MCP Connection Manager** - Lifecycle management for server connections
-- **gen_client** - Context manager for temporary connections
-- **connect/disconnect** - Persistent connection management
+- `MCPConnectionManager` keeps track of connection health and will surface errors via logs (`ProgressAction.FATAL_ERROR`) without crashing your application.
+- Call `disconnect_all()` or `close()` if you want to force reconnection after rotating credentials.
+- When a connection fails during initialisation, any awaiting `get_server` call unblocks with an exception so that workflows can decide whether to retry or degrade gracefully.
 
-[See MCP Servers documentation for details →](/mcp-agent-sdk/core-components/mcp-servers)
+[Deep dive into MCP Servers →](/mcp-agent-sdk/core-components/mcp-servers)

docs/mcp-agent-sdk/core-components/execution-engine.mdx

@@ -47,8 +47,9 @@ The Temporal engine provides durable workflow execution with automatic state per
 ```yaml
 execution_engine: temporal
 temporal:
-  server_url: "localhost:7233"
+  host: "localhost:7233"
   namespace: "default"
+  task_queue: "mcp-agent"
 ```
 
 **Use cases:**
@@ -58,6 +59,8 @@ temporal:
 - Multi-node deployments
 - Workflows requiring pause/resume
 
+📌 **Example:** The [Temporal workflow gallery](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/temporal) showcases orchestrator, router, and evaluator/optimizer patterns running on this engine.
+
 ## Executors
 
 Executors are the runtime components that actually execute workflows within an engine.
@@ -67,29 +70,38 @@ Executors are the runtime components that actually execute workflows within an e
 Handles workflow execution for the asyncio engine:
 
 ```python
-from mcp_agent.executors.asyncio_executor import AsyncioExecutor
+from mcp_agent.executor.executor import AsyncioExecutor
+
+async def greet(name: str) -> str:
+    return f"Hi {name}"
 
 executor = AsyncioExecutor()
-result = await executor.execute_workflow(workflow, params)
+result = await executor.execute(greet, "Ada")
+print(result)  # "Hi Ada"
 ```
 
 **Features:**
 - Direct Python function execution
 - Native async/await support
 - Minimal overhead
 
+See it in action in the [basic workflows examples](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/workflows) where tasks run entirely in-process.
+
 ### TemporalExecutor
 
 Manages workflow execution for the Temporal engine:
 
 ```python
-from mcp_agent.executors.temporal_executor import TemporalExecutor
-
-executor = TemporalExecutor(
-    temporal_host="localhost:7233",
-    namespace="default"
-)
-result = await executor.execute_workflow(workflow, params)
+from mcp_agent.executor.temporal import TemporalExecutor
+from mcp_agent.config import TemporalSettings
+
+executor = TemporalExecutor(config=TemporalSettings(
+    host="localhost:7233",
+    namespace="default",
+    task_queue="mcp-agent",
+))
+handle = await executor.start_workflow("ResearchWorkflow", {"topic": "LLMs"})
+result = await handle.result()
 ```
 
 **Features:**
@@ -98,6 +110,8 @@ result = await executor.execute_workflow(workflow, params)
 - Distributed execution
 - Workflow queries and signals
 
+The [`examples/oauth/pre_authorize`](https://github.com/lastmile-ai/mcp-agent/tree/main/examples/oauth/pre_authorize) project combines this executor with OAuth-aware workflows.
+
 ## Choosing an Execution Engine
 
 ### Development Phase
@@ -200,15 +214,27 @@ logger:
 ```yaml
 execution_engine: temporal
 temporal:
-  server_url: "temporal.production.internal:7233"
+  host: "temporal.production.internal:7233"
   namespace: "production"
   task_queue: "agent-workflows"
   worker_count: 4
   max_concurrent_activities: 20
 ```
 
+## Accessing the executor in an application
+
+`MCPApp` exposes the active executor and engine selection:
+
+```python
+async with app.run() as running_app:
+    executor = running_app.executor
+    print(executor.execution_engine)  # "asyncio" or "temporal"
+```
+
+You typically call high-level helpers (`workflow.execute()`, `executor.start_workflow`) rather than invoking executor methods directly, but the property is available when you need advanced control or diagnostics.
+
 ## Next Steps
 
 - [Temporal Advanced Features](/advanced/temporal)
 - [Workflow Patterns](/workflows/overview)
-- [Configuration Guide](/configuration)
+- [Configuration Guide](/configuration)