MCP tools

The nano-banana MCP server exposes four tools. They all map onto the same pipeline-core helpers that power the web app, so behavior is identical modulo who triggers the call.

propose_concepts

Synchronous. Turns a rough idea into one stylistically coherent visual concept, with a refined prompt + thematic keywords + an id of the form <pipelineId>#0 that can be fed back into generate_image via concept_id.

{
  "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 is always a single-element array today — the architect emits one refined concept per call. To explore alternative directions, call propose_concepts again with a tweaked prompt; to explore visual variants of the same concept, use generate_image_async with iterations: 2..4 on the returned id.

generate_image (synchronous)

Blocks up to 180 seconds while the pipeline runs, streams progress notifications, returns final signed GCS URLs. Best for interactive flows where the human is actively watching.

{
  "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"
}

Returns:

{
  "images": [
    {
      "pipeline_id": "def-456",
      "status": "completed",
      "results": [
        { "image": "<7d signed GCS URL>", "image_uri": "gs://...", "thumbnail": "..." }
      ]
    }
  ],
  "duration_ms": 47213
}

generate_image_async

Same input shape as generate_image, but returns immediately with pipeline_ids. Use this when you want to fire-and-forget several pipelines and poll them in parallel, or when the model expects to be free while images render.

Returns:

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

get_image

Snapshot or long-poll on one pipeline.

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

• wait_seconds: 0 (default): instant snapshot.
• wait_seconds: 1..270: blocks up to N seconds, returns whenever status transitions to completed or failed (or the deadline passes).

Returns:

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

Tool selection cheat sheet

Scenario	Tool combination
"Make me an image of X"	generate_image (raw prompt, auto-styled via prompt-engineer)
"Show me a direction first"	propose_concepts → user accepts/refines → generate_image (concept_id)
Bulk variations in parallel	generate_image_async (iterations: 4) → wait → get_image
Long-running flow that survives client restart	generate_image_async → get_image with wait_seconds