MCP-Tools

Der nano-banana MCP Server exposed vier Tools. Sie zielen alle auf dieselben pipeline-core-Helper, die auch die Web-App nutzt — das Verhalten ist also identisch, egal wer den Call auslöst.

Alle vier Tools liefern sowohl einen menschenlesbaren text-Content-Block (JSON, aus Abwärtskompatibilität beibehalten) als auch ein typisiertes structuredContent-Objekt, das gegen ein Output-Schema validiert wird. Programmatische Aufrufer (Agents, MCP-Clients) sollten structuredContent konsumieren statt den Text-Block zu parsen.

Per-User-Quote

Jeder Call von propose_concepts, generate_image oder generate_image_async zählt als eine Einheit gegen deine Tages- / Stundenquote — iterations multipliziert nicht. get_image ist frei. Defaults: 300 / Tag, 60 / Stunde pro User. Bei Quota-Erschöpfung kommt ein Tool-Error zurück, den der Claude-Client anzeigt. Details unter MCP Auth & Operations → Quoten.

propose_concepts

Synchron. Verwandelt eine grobe Idee in ein stilistisch kohärentes visuelles Concept, mit refined Prompt + thematischen Keywords + einer id der Form <pipelineId>#0, die man via concept_id zurück in generate_image füttern kann.

Tool-Annotations: seiteneffektbehaftet (readOnlyHint: false, idempotentHint: false, openWorldHint: true).

{
  "prompt": "marketing hero for our gemini enterprise launch",
  "conversationId": "optional, for stitching multi-turn sessions"
}

Returns:

{
  "pipelineId": "abc-123",
  "concepts": [
    {
      "id": "abc-123#0",
      "title": "Translucent prism",
      "refined_prompt": "…full styled prompt the diffusion model will see…",
      "keywords": ["isometric", "translucent", "blue"]
    }
  ]
}

concepts ist heute immer ein einelementiges Array — der Architect emittiert pro Call ein refined Concept. Wer alternative Richtungen erkunden will, ruft propose_concepts mit einem leicht veränderten Prompt nochmal auf; wer visuelle Varianten desselben Concepts will, nutzt generate_image_async mit iterations: 2..4 auf der zurückgegebenen id.

generate_image (synchron)

Blockt bis zu 180 Sekunden, während die Pipeline läuft, streamt Progress-Notifications und liefert am Ende final signed GCS URLs zurück. Am besten für interaktive Flows, in denen ein Mensch aktiv zuschaut.

Tool-Annotations: seiteneffektbehaftet (readOnlyHint: false, idempotentHint: false, openWorldHint: true).

{
  "prompt": "raw user prompt (optional if concept_id provided)",
  "concept_id": "abc-123#0 (optional, supersedes prompt)",
  "refinement": "optional free-text tweak applied on top of concept",
  "aspectRatio": "1:1 | 16:9 | 9:16 | 4:3 | 3:4",
  "iterations": 1,
  "enhance": true,
  "resolution": "1k | 2k | 4k",
  "response_format": "concise"
}

response_format (Default: concise):

Wert	Zurückgegebene Felder pro Ergebnis
concise	image (Signed URL), inline-Status
detailed	wie oben + image_uri (gs://…) und prompt

Im Modus detailed enthält das Top-Level-Antwortobjekt zusätzlich duration_ms (nur generate_image).

Returns (concise):

{
  "images": [
    {
      "pipeline_id": "def-456",
      "status": "completed",
      "results": [
        { "image": "<7d signed GCS URL>", "inline": "ok" }
      ]
    }
  ]
}

Im detailed-Modus wird duration_ms auf Toplevel ergänzt und jedes Ergebnis enthält zusätzlich image_uri und prompt.

generate_image_async

Gleiches Input-Schema wie generate_image (ohne response_format), kommt aber sofort mit pipeline_ids zurück. Sinnvoll, wenn man mehrere Pipelines fire-and-forget anstoßen und parallel pollen will, oder wenn das Modell währenddessen frei bleiben soll.

Tool-Annotations: seiteneffektbehaftet (readOnlyHint: false, idempotentHint: false, openWorldHint: true).

Returns:

{ "pipeline_ids": ["def-456", "def-457"], "status": "running" }

get_image

Snapshot oder Long-Poll auf eine einzelne Pipeline.

Tool-Annotations: lesend und idempotent (readOnlyHint: true, idempotentHint: true, openWorldHint: true).

{
  "pipeline_id": "def-456",
  "wait_seconds": 270,
  "response_format": "concise"
}

• wait_seconds: 0 (Default): Instant-Snapshot.
• wait_seconds: 1..270: blockt bis zu N Sekunden, kommt zurück, sobald Status auf completed oder failed springt (oder die Deadline läuft ab).

response_format (Default: concise):

Wert	Zurückgegebene Felder pro Ergebnis
concise	image (Signed URL), inline-Status
detailed	wie oben + image_uri (gs://…) und prompt

Returns:

{
  "pipeline_id": "def-456",
  "status": "running",
  "progress_percent": 60,
  "stage": "enhance-image",
  "results": []
}

Tool-Auswahl auf einen Blick

Szenario	Tool-Kombination
"Mach mir ein Bild von X"	generate_image (roher Prompt, wird via Prompt Engineer gestyled)
"Zeig mir erstmal eine Richtung"	propose_concepts → User akzeptiert/refined → generate_image (concept_id)
Bulk-Varianten parallel	generate_image_async (iterations: 4) → warten → get_image
Langläufer, der Client-Restart überlebt	generate_image_async → get_image mit wait_seconds