MCP server that gives any AI client image generation and image understanding via the Agnes API
Three tools with complete schemas and detailed descriptions. generate_image and describe_image have excellent, LLM-optimized descriptions (200+ chars) with clear usage guidance and constraints. set_api_key is well-documented. All tools have proper input schemas with types and descriptions. However, output schemas are not formally documented, generate_image returns a list with a string and Image object, but the Image format is not described in the tool definition. Parameter descriptions are strong (e.g., reference_images includes nuanced guidance on behavior). No enum constraints on size/ratio parameters despite fixed valid values. Error handling is implicit (RuntimeError messages are good but not categorized as retryable/fatal). Missing tool annotations (readOnlyHint, destructiveHint, idempotentHint) for agent planning.
Look at one or more images and answer a question about them. Gives vision to a text-only model. Useful for: reading text in a screenshot, describing a photo, checking whether a generated image matches a brief, comparing two images, extracting data from a chart.
Generate an image from a text prompt. Returns the image itself. HOW MANY reference_images you pass decides whether the model obeys you. This matters more than prompt wording: 0 refs -> art style and composition instructions are followed exactly. The look of any character must be described in words. 1 ref -> keeps the referenced character's likeness AND follows pose instructions, BUT the art style will follow the reference, not your prompt. Use for expression sets / same character, new pose. 3+ refs -> the model starts copying instead of creating. Pose and style instructions stop working; it reproduces the reference, including its background props and artifacts. Avoid. Style control and likeness control cannot both be had in one call. Decide which one this image needs. To get both: generate once with 0 refs to fix the style, then use that output as the single ref for follow-ups. Hard limit: 6 reference images, more returns HTTP 400.
Set up this server with the user's API key. This is the whole install: save the key, then prove both capabilities actually work end to end. Call this as soon as the user provides a key. Report the returned message back to them verbatim — it is the completion notice. Works with both Agnes endpoints — the global one (agnes-ai.com) and the mainland China one (platform.agnes-ai.cn). Do not ask the user which one they signed up on: whichever accepts the key is detected here and saved with it, so every later call goes straight to the right endpoint. The key is verified before being written, so a typo fails here rather than on the first real request. It is stored in plain text at ~/.agnes-image-mcp-key on this machine only, and is sent only to Agnes. AGNES_API_KEY in the environment still wins if set.
Output schemas not formally documented. generate_image returns [str, Image] but Image format (data, format fields) is not described in tool definition. Agents cannot plan downstream processing without knowing return structure.
size and ratio parameters accept free-form strings without enum constraints. Should declare valid values (e.g., size: ['1024x1024', '1K', '2K'], ratio: ['1:1', '16:9']) to prevent LLM hallucination of invalid dimensions.
Tool annotations missing. generate_image and set_api_key are destructive (write files, modify state); describe_image is read-only. Adding destructiveHint/readOnlyHint helps agents reason about side effects and retry safety.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 62 | 2026-07-28+ | v2 |
Error messages are informative but not categorized. RuntimeError for 'no model matching pattern' is fatal; 'key not accepted by either endpoint' is user-fixable. Explicit error classification (retryable, user-fixable, fatal) guides agent recovery.
API key stored in plaintext at ~/.agnes-image-mcp-key. While documented, this is a security risk. Consider recommending encrypted storage or OS keyring integration in the README.