MCP client/server "missing field user_agent" error in v0.32.x - regression from PR #3395

What version of Codex is running?

v0.32.0 (regression), v0.31.0 works

Which model were you using?

GPT 5

What platform is your computer?

Mac OS

What steps can reproduce the bug?

Steps to reproduce the bug

1. Install codex-cli v0.32.0 (the latest version with the regression)

1. Add an MCP server configuration to ~/.codex/config.toml:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

1. Start codex CLI:

codex

1. Error occurs immediately: MCP client/server fails to start with "missing field user_agent" error.

Root Cause Analysis

The issue is in PR #3395 which introduced changes to MCP client initialization. The user_agent field became a required field in the MCP client/server communication, but:

1. user_agent cannot be configured via config.toml - there's no documented way to set it
2. The code sets user_agent programmatically - but this seems to fail in v0.32.x
3. Downgrading to v0.31.0 works perfectly - confirming this is a regression

Sample Working Config (v0.31.0)

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
# user_agent = "Codex CLI"  # This field should not be required in config

What is the expected behavior?

MCP servers should initialize successfully as they did in v0.31.0 and earlier versions.

The user_agent field should be:

• Set automatically by the client (programmatically in the code)
• NOT required to be configured manually in config.toml
• Work out-of-the-box with standard MCP server configurations

Users should be able to configure MCP servers in their config.toml using the documented format:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

And the servers should start without any "missing field" errors.

What do you see instead?

MCP client for context7 failed to start: missing field user_agent error message.

The MCP server initialization fails completely and the user cannot use any MCP functionality.

Error details:

• Error message: "missing field user_agent"
• Impact: MCP servers completely non-functional
• Timing: Occurs immediately on startup when MCP servers are configured
• Scope: Affects all MCP servers in config.toml, not just context7

Current workaround:

• Downgrade to v0.31.0 which works perfectly
• OR manually add user_agent = "Codex CLI" to config (though this shouldn't be required)

Additional information

Recommended Solutions

1. Fix the regression in PR #3395 to automatically set user_agent programmatically
2. OR Update documentation to clearly show user_agent is now required in config.toml
3. OR Revert the changes to allow user_agent omission as in v0.31.0

Related Issues & Context

• Primary issue: This is related to issue #3424 but provides much more comprehensive detail
• Regression PR: #3395 introduced this breaking change
• Prior working version: v0.31.0 works perfectly
• MCP Server: context7 (but affects all MCP servers)
• Environment tested: Ubuntu 24.04 LTS

Impact Assessment

• Severity: High - breaks all MCP functionality
• User base affected: All users with MCP server configurations
• Workaround complexity: Requires version downgrade or undocumented config changes

Sample Config for Testing

# ~/.codex/config.toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
# user_agent = "Codex CLI"  # Should not be needed!

This configuration works in v0.31.0 but fails in v0.32.x with the user_agent error.

Request: Please either fix the programmatic user_agent setting or provide clear documentation on how to configure it properly.