Skip to main content
mcp-agent uses YAML configuration files to manage application settings, MCP servers, and model providers.

​
Configuration files

Start with two YAML files at the root of your project:

mcp_agent.config.yaml

Application configuration, MCP servers, logging, execution engine, model defaults

mcp_agent.secrets.yaml

API keys, OAuth credentials, and other secrets (gitignored)
See Specify Secrets for credential management patterns and production tips.

​
Basic configuration

Here’s a minimal configuration: 
execution_engine: asyncio
logger:
  transports: [console]
  level: info

mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]

openai:
  default_model: gpt-4o

​
Execution Engine

Choose how your workflows execute:
In-memory execution for development and simple deployments:
execution_engine: asyncio
Best for:
  • Local development
  • Simple agents
  • Quick prototyping
Learn more about Execution Engines →

​
Logging

Configure logging output and level:
mcp_agent.config.yaml
logger:
  transports: [console, file]  # Output to console and file
  level: info  # debug, info, warning, error
  path: "logs/mcp-agent.jsonl"  # For file transport
You can also use dynamic log filenames: 
logger:
  transports: [file]
  level: debug
  path_settings:
    path_pattern: "logs/mcp-agent-{unique_id}.jsonl"
    unique_id: "timestamp"  # Or "session_id"
    timestamp_format: "%Y%m%d_%H%M%S"
Learn more about Logging →

​
MCP Servers

Define MCP servers your agents can connect to:
mcp_agent.config.yaml
mcp:
  servers:
    fetch:
      command: "uvx"
      args: ["mcp-server-fetch"]
      description: "Fetch web content"

    filesystem:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
      description: "Local filesystem access"

    sqlite:
      command: "uvx"
      args: ["mcp-server-sqlite", "--db-path", "data.db"]
      description: "SQLite database operations"
Learn more about MCP Servers →

​
Model Providers

Configure your LLM provider. Many examples follow this layout—for instance, the basic finder agent sets OpenAI defaults exactly this way.
mcp_agent.config.yaml
openai:
  default_model: gpt-4o
  temperature: 0.7
  max_tokens: 4096
mcp_agent.secrets.yaml
openai:
  api_key: "sk-..."

​
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.
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 and the interactive OAuth tool. The pre-authorize workflow example 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. 
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 covers strategies for each stage.

​
Environment Variables

You can reference environment variables in configuration:
mcp_agent.config.yaml
openai:
  default_model: ${OPENAI_MODEL:-gpt-4o}  # Default to gpt-4o

temporal:
  host: ${TEMPORAL_HOST:-localhost:7233}
Use environment variables for deployment-specific settings like endpoints and regions, while keeping model choices in the config file.

​
Project Structure

Recommended project layout: 
your-project/
├── agent.py                  # Your agent code
├── mcp_agent.config.yaml     # Application configuration
├── mcp_agent.secrets.yaml    # API keys (gitignored)
├── .gitignore                # Ignore secrets file
├── requirements.txt          # Python dependencies
└── logs/                     # Execution logs
Add to .gitignore: 
mcp_agent.secrets.yaml
logs/
*.log

​
Complete Configuration Reference

For all available configuration options, see the Configuration Reference.

​
Next Steps

Specify Secrets

Learn about secrets management

MCPApp

Understand the application context

Agents

Create your first agent

Configuration Reference

Complete configuration documentation