Add image input support to MCP server tools
Resolved 💬 1 comment Opened Jan 21, 2026 by sorryhyun Closed Feb 23, 2026
What feature would you like to see?
Summary
The codex and codex-reply MCP tools currently only accept text prompts. Image inputs should be supported to match the capabilities of other Codex interfaces (CLI, TUI, app-server).
Current Behavior
When running Codex as an MCP server, the tool schema only exposes a prompt string parameter:
{
"name": "codex",
"inputSchema": {
"properties": {
"prompt": { "type": "string" }
}
}
}
There is no way to pass images through the MCP tool interface.
Expected Behavior
Users should be able to pass images alongside text prompts, similar to the CLI:
codex -i screenshot.png "Explain this error"
Technical Context
The underlying protocol already supports images via UserInput::Image and UserInput::LocalImage variants in codex-rs/protocol/src/user_input.rs:
pub enum UserInput {
Text { text: String, text_elements: Vec<TextElement> },
Image { image_url: String }, // Data URI or HTTP(S) URLs
LocalImage { path: std::path::PathBuf }, // Local file paths
Skill { name: String, path: std::path::PathBuf },
}
However, the MCP server hardcodes text-only submissions in codex-rs/mcp-server/src/codex_tool_runner.rs:
let submission = Submission {
op: Op::UserInput {
items: vec![UserInput::Text {
text: initial_prompt.clone(),
text_elements: Vec::new(),
}],
...
},
};
Proposed Solution
- Add an
imagesfield toCodexToolCallParamandCodexToolCallReplyParamincodex-rs/mcp-server/src/codex_tool_config.rs:
#[derive(Deserialize, JsonSchema)]
pub struct CodexToolCallParam {
pub prompt: String,
/// Image URLs (http/https) or base64 data URIs
#[serde(default)]
pub images: Vec<String>,
// ... existing fields
}
- Update
codex_tool_runner.rsto convert image URLs intoUserInput::Imageitems alongside the text input.
- Update the MCP interface documentation in
codex-rs/docs/codex_mcp_interface.md.
Additional information
Use Cases
- Passing screenshots to Codex for debugging UI issues
- Sharing design specs or mockups for implementation
- Analyzing diagrams or architecture drawings
- Any workflow where the MCP client has access to images that would help Codex understand the task
Additional Context
- CLI/exec supports images via
--image/-iflags - TUI supports pasting/attaching images
- App-server supports images via
ContentItem::InputImage - Only the MCP server interface lacks this capability
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗