docs: add troubleshooting for MCP timeout and Codex permissions

[cexll]

…sions

• Add MCP_TOOL_TIMEOUT environment variable configuration
• Add Codex CLI config.toml setup for file write permissions
• Include cross-platform instructions (Linux/macOS/Windows)
• Add security warning for danger-full-access mode

Fixes #1

Generated by swe-agent

Description

Related Issue

Fixes #(issue number)

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update
• 🎨 Code style/refactoring
• ⚡ Performance improvement
• ✅ Test addition/modification
• 🔧 Configuration change

Changes Made

Testing

Test Configuration

• Node.js version:
• Codex CLI version:
• Operating System:

Test Steps

Test Results

Tool-Specific Testing

• ask-codex
• brainstorm
• ping
• help
• fetch-chunk
• timeout-test
• N/A - Core functionality change

Breaking Changes

• This PR includes breaking changes

If yes, describe:

• What breaks:
• Migration path:
• Affected users:

Documentation

• README.md updated
• API documentation updated
• VitePress docs updated
• Code comments added/updated
• CHANGELOG.md updated
• No documentation needed

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have tested my changes locally with npm run lint
• I have tested my changes locally with npm run build
• I have tested the MCP integration with a real client (Claude Desktop/Code)
• Any dependent changes have been merged and published

Additional Notes

Screenshots

Reviewer Notes

---

For Maintainers:

• Changes reviewed
• Tests pass
• Documentation complete
• Ready to merge

---

Note

Adds a README troubleshooting section for MCP tool timeouts and Codex file write permissions with cross‑platform steps and a security warning.

• Documentation (README.md)
  • Common Issues section added:
    • MCP Tool Timeout Error: Instructions to set MCP_TOOL_TIMEOUT (Unix, PowerShell, CMD) and persist via shell profile.
    • Codex Cannot Write Files: Add ~/.codex/config.toml with approval_policy = "never", sandbox_mode = "danger-full-access", and related settings; includes security warning.
    • Config file locations for macOS/Linux (~/.codex/config.toml) and Windows (%USERPROFILE%\.codex\config.toml).
    • Note to restart MCP client after updating configuration.

^{Written by Cursor Bugbot for commit 23c56b6. This will update automatically on new commits. Configure here.}