Get Image (Research)

researchmcp-research_get_image

Fetch a single image by its stable id.

Use after research_image_search or research_match_images_to_text when you have an image_id. The response always includes the image metadata (URL, caption, copyright, format); pass include_bytes=True to also include the base64 image bytes for multimodal LLM input.

image_id is an opaque id assigned when the image is indexed. It round-trips reliably within a session (search -> get). It is NOT durable across re-ingestion: the hourly cron deletes a report's docs and re-inserts them with new ids when the report is modified, so an image_id obtained before reprocessing will miss afterward. Fetch within the same session.

Parameters

Name	Type	Required	Constraints	Description
image_id	string	yes	—	The image_id returned by a previous research_image_search or research_match_images_to_text call.
include_bytes	boolean	no	default: false	When true, the response carries the base64-encoded image bytes in bytes_base64. Default false to keep payloads small; opt in only when you need the actual image (e.g. for multimodal LLM input).

Returns

• On hit: {"result": {
• "image": {report_id, title, date, score, url, caption, copyright,
• format, image_id},
• "bytes_base64": str | None,
• "format": str | None,
• }}
• On miss: {"result": {"image": None, "bytes_base64": None, "format": None}}.
• On retrieval failure: {"error": {code, message}}
• code is upstream_unavailable, internal (our own bad
• data; a retry returns the same error), or not_entitled (authorization
• refused).
• bytes_base64 is populated only when include_bytes=True and the image is
• found. format is a top-level convenience copy of image.format.
• No tags here, unlike a search hit: the image search that gave you this
• image_id already returned the report's taxonomy tags. If you need the
• audience/season of the parent report and no longer have them, call
• research_get_report(report_id).
• The score field is 0.0 for direct id lookups (no relevance ranking applies).

Try it

Loading interactive widget…

Code examples

curl

curl -s https://mcp.edited.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -H "x-api-key: $MCP_API_KEY" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "researchmcp-research_get_image",
    "arguments": {
      "image_id": "example",
      "include_bytes": false
    }
  }
}'

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "demo", version: "1.0.0" }, { capabilities: {} });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://mcp.edited.com/mcp"), {
    requestInit: { headers: { "x-api-key": process.env.MCP_API_KEY ?? "" } },
  }),
);

const result = await client.callTool({
  name: "researchmcp-research_get_image",
  arguments: {
    "image_id": "example",
    "include_bytes": false
  },
});

Python

import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

headers = {"x-api-key": os.environ["MCP_API_KEY"]}
async with streamablehttp_client("https://mcp.edited.com/mcp", headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "researchmcp-research_get_image",
            {"image_id": "example", "include_bytes": False},
        )

Input schema

{
  "type": "object",
  "properties": {
    "image_id": {
      "description": "The image_id returned by a previous research_image_search or research_match_images_to_text call.",
      "minLength": 1,
      "type": "string"
    },
    "include_bytes": {
      "default": false,
      "description": "When true, the response carries the base64-encoded image bytes in `bytes_base64`. Default false to keep payloads small; opt in only when you need the actual image (e.g. for multimodal LLM input).",
      "type": "boolean"
    }
  },
  "required": [
    "image_id"
  ]
}

Output schema

Describes both branches of the envelope — result on success, error on a refusal. Validate against this rather than pattern-matching the prose above; see Concepts → Response shape.

{
  "type": "object",
  "properties": {
    "result": {
      "properties": {
        "image": {
          "anyOf": [
            {
              "properties": {
                "report_id": {
                  "type": "integer"
                },
                "title": {
                  "type": "string"
                },
                "date": {
                  "format": "date",
                  "type": "string"
                },
                "score": {
                  "type": "number"
                },
                "url": {
                  "type": "string"
                },
                "caption": {
                  "type": "string"
                },
                "copyright": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "format": {
                  "anyOf": [
                    {
                      "enum": [
                        "png",
                        "jpeg",
                        "webp",
                        "jpg"
                      ],
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "image_id": {
                  "type": "string"
                }
              },
              "required": [
                "report_id",
                "title",
                "date",
                "score",
                "url",
                "caption",
                "copyright",
                "format",
                "image_id"
              ],
              "type": "object"
            },
            {
              "type": "null"
            }
          ]
        },
        "bytes_base64": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Null unless include_bytes was requested and the image was found."
        },
        "format": {
          "anyOf": [
            {
              "enum": [
                "png",
                "jpeg",
                "webp",
                "jpg"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "description": "Copy of image.format, for convenience."
        }
      },
      "required": [
        "image",
        "bytes_base64",
        "format"
      ],
      "type": "object"
    },
    "error": {
      "type": "object",
      "description": "Present instead of `result` when the call was rejected. Branch on `code`; never string-match `message`.",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "invalid_input",
            "not_entitled",
            "upstream_unavailable",
            "internal"
          ]
        },
        "message": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "description": "Offending parameter, when the failure is attributable to one."
        },
        "details": {
          "type": "object",
          "additionalProperties": true
        }
      },
      "required": [
        "code",
        "message"
      ]
    }
  },
  "oneOf": [
    {
      "required": [
        "result"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ],
  "x-fastmcp-wrap-result": true
}