Per-project MCP server configuration in .codex/config.toml or mcp.json (avoid wrapper scripts)

[wachterjohannes]

What variant of Codex are you using?

Codex CLI (with project-level .codex/config.toml)

What feature would you like to see?

I’d like first-class support for configuring MCP servers per project/directory, either in .codex/config.toml and/or via mcp.json.

Today, the current config level is not enough for workflows where MCP servers need to be started with directory-specific context. Tools like ai-mate use a per-directory MCP server model, but in Codex this is hard to express cleanly.

Current workaround: wrapper scripts that inject the project path or dynamic context before launching the MCP server. This works, but it adds setup complexity and is not a great UX.

A concrete example is this Symfony AI integration PR, which needed a wrapper-based approach:
symfony/ai#1682

Requested outcome:

1. Allow native per-project/directory MCP server configuration.
2. Support this cleanly through .codex/config.toml and/or mcp.json.
3. Remove the need for wrapper scripts in common integrations.
4. Make MCP behavior more predictable and ergonomic across projects.

This came up in the PR discussion here (which was closed):
#12718
I understand why that PR was closed, but I think this use case still needs a proper configuration-level solution.

Additional information

If helpful, I can propose concrete config shape options (for example, project-scoped server entries, per-workspace overrides, or variable interpolation for the current directory) and help test them against real integrations.

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• Codex Desktop ignores project .codex/config.toml MCP server (Serena) and only loads ~/.codex/config.toml #13025
• App-server config write APIs cannot target project .codex/config.toml (user config only) #11728

Powered by Codex Action

[xXMrNidaXx]

Per-Project MCP Configuration - Design Patterns

Strong +1 for this. Having worked with MCP integrations across multiple agent frameworks, the wrapper-script workaround is a real pain point. Here are some patterns that could work well:

1. Config Shape Options

Option A: Direct .codex/config.toml extension

[mcp.servers.my-project-server]
command = "npx"
args = ["-y", "@myorg/project-mcp"]
env = { PROJECT_ROOT = "${workspaceFolder}" }

Option B: Separate mcp.json (VSCode-style)

{
  "servers": {
    "project-context": {
      "command": "node",
      "args": ["./tools/mcp-server.js"],
      "cwd": "${workspaceFolder}",
      "env": {
        "DB_PATH": "${workspaceFolder}/data/local.db"
      }
    }
  }
}

2. Variable Interpolation (Critical)

Key variables to support:

• ${workspaceFolder} - Project root
• ${cwd} - Current working directory
• ${env:VAR_NAME} - Host environment variables
• ${file} - Currently focused file (if applicable)

3. Lifecycle Considerations

MCP servers often need different lifecycles:

• Persistent: Start once, reuse across sessions (LSP-style)
• Ephemeral: Spin up per-invocation (sandbox workflows)
• Lazy: Start on first tool call

[mcp.servers.heavy-analyzer]
lifecycle = "persistent"
startup_timeout_ms = 5000

4. Config Precedence

Recommend clear layering:

1. Project .codex/config.toml (highest priority)
2. User-level ~/.codex/config.toml
3. System defaults

With explicit merge strategy (override vs extend).

5. Real-World Use Case

Framework integrations (Symfony, Rails, Django) need this badly. Each framework has its own context (routes, models, services) that an MCP server should understand. Currently everyone builds wrapper scripts like:

#!/bin/bash
export SYMFONY_PROJECT=$(pwd)
exec npx @symfony-ai/mcp-server

This would be cleaner as native config with ${workspaceFolder}.

Happy to help test against real integrations if you ship an experimental flag!

---

Building AI integrations at RevolutionAI - we hit this pattern constantly with client projects.