Configuration Reference

MCP Director uses a YAML file for configuration.

Configuration Discovery

The application searches for the configuration file in the following order:

1. Environment Variable: MCP_DIRECTOR_CONFIG (full path to the file)
2. Local Directory: ./config/default.yaml (relative to the current working directory)
3. Parent Directory: ../../config/default.yaml (useful when running from an app subdirectory)
4. Home Directory: ~/.mcp-director/config.yaml (global user configuration)

If no configuration file is found, the server will use sensible default settings.

Global Settings

version: "1.0"

settings:
  log_level: info  # info, debug, error, warn, trace

  namespace_strategy: prefix  # prefix or flat
  # prefix: Tools will be named "server/tool_name"
  # flat: Tools keep their original name (conflicts may occur)

  protocol_version: "2025-11-25"  # Latest MCP protocol version

HTTP Settings

settings:
  http:
    enabled: true
    host: "127.0.0.1"
    port: 3000
    localhost_only: true
    allowed_origins:
      - "http://localhost:3000"
    allowed_methods:
      - GET
      - POST
      - DELETE
      - OPTIONS
    allowed_headers:
      - Authorization
      - Content-Type
      - Accept
      - X-CSRF-Token
    rate_limit:
      requests_per_minute: 120
    max_body_bytes: 1048576

STDIO Settings

settings:
  stdio:
    enabled: true  # Must be true for Claude Desktop

Web UI Settings

settings:
  web:
    enabled: true  # Serves the web dashboard from the HTTP server

Authentication

settings:
  auth:
    enabled: true
    username: admin
    password_hash: "$2b$12$..."  # Bcrypt hash

TIP

Use mcp-director auth enable --reset-password -p "your-password" to set up authentication.

Servers

Define MCP servers to aggregate:

servers:
  filesystem:
    transport: subprocess
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    env:
      DEBUG: "true"

  remote-api:
    transport: http
    url: https://api.example.com/sse

Projects

Group servers into projects:

projects:
  dev:
    servers: [filesystem, github]
    overrides:
      filesystem:
        env:
          DEBUG: "true"
        args: ["--verbose"]

Profiles

Control access and limits for clients:

profiles:
  restricted:
    tools_whitelist: ["filesystem/*"]
    tools_blacklist: ["filesystem/delete_*"]
    log_requests: false
    allow_all_servers: false
    allowed_projects: ["dev"]
    auth:
      enabled: true
      token: "replace-with-generated-token"
    rate_limit:
      requests_per_minute: 10
    time_restriction:
      allowed_days: [1, 2, 3, 4, 5]  # Monday-Friday
      start_hour: 9
      end_hour: 18

INFO

Time restrictions use 24-hour local time. allowed_days is 1-7 with Monday=1 and Sunday=7.

Environment Variables

You can use environment variables in the config file:

servers:
  my-server:
    env:
      API_KEY: ${MY_API_KEY}

Disabled Tools

Globally disable specific tools:

settings:
  disabled_tools:
    - "filesystem/delete_file"
    - "dangerous/tool"