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

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

• #13025
• #11728

Powered by Codex Action

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.

From what I can tell, .mcp.json has become the most common standard for project-level MCP. Projects are willing to absorb a .mcp.json in their repos, but they're not gonna be willing to have different configuration mechanisms for every different agent.
I think it'd be essential for Codex to adopt picking up project-level .mcp.json sooner than later, I've already seen people dismiss Codex entirely simply over not supporting this.

This would be very useful for our workflow as well.

At work we rely heavily on project-local .mcp.json files with Claude Code to connect coding agents to app-development MCP servers.

A concrete example is Tidewave MCP in Elixir/Phoenix projects, which exposes development capabilities such as fetching logs, evaluating code in the app context, running queries, and inspecting runtime state.

This already works in Codex when configured manually through config.toml, but in our case we have many microservices/MVPs and each service may expose its MCP server on a different local port. With ~20 services, maintaining those MCP entries globally or manually editing ports becomes painful.

Project-local .mcp.json support would let each service declare its own MCP endpoint next to the codebase. Codex could detect it, ask for approval in the TUI, and connect to it for that workspace.

Trusted project .codex/config.toml files now support MCP servers.