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

  1. Add an images field to CodexToolCallParam and CodexToolCallReplyParam in codex-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
}
  1. Update codex_tool_runner.rs to convert image URLs into UserInput::Image items alongside the text input.
  1. 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 / -i flags
  • TUI supports pasting/attaching images
  • App-server supports images via ContentItem::InputImage
  • Only the MCP server interface lacks this capability

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗