MCP Tools Overview

Complete reference for all 53 MCP tools available in Go Bananas!. The local STDIO proxy (gobananas-mcp) adds one more, go_bananas_diagnose, for checking its own connection (CLI guide). Subscription entries describe an experimental capability available to signed-in users in the public deployment and disabled by default for self-hosting. Tool visibility is not proof of runner availability; see subscription readiness.

Tool Categories

ChatGPT Subscription

OAuth user-scoped generation through the subscription connected on the Go Bananas website:

Tool	Purpose	Key Parameters
get_subscription_status	Check the connected subscription	none
generate_with_subscription	Generate and save one PNG without provider API fallback	prompt, aspect_ratio

View Subscription Tools →

Image Generation & Editing

Core tools for creating and modifying images:

Tool	Purpose	Key Parameters
generate_image	Create new images	prompt, aspect_ratio, n
generate_poster	Create posters and campaign assets	brief, style, title, subtitle, palette
list_poster_styles	Browse poster style IDs	none
request_higgsfield_video	Submit image-to-video job	image_id/image_url, prompt, duration
get_higgsfield_video_status	Poll video job	request_id
edit_image	Edit by ID	image_id, prompt
upload_image_for_editing	Upload for editing	image_url, file_name
edit_uploaded_image	Edit uploads	image_id, edit_prompt
upload_media	Upload durable media	file_path or media_url
continue_editing	Conversational edit	prompt
batch_generate	Parallel batch generation	items (1-8), defaults
get_image_info	Image metadata	image_id
get_session_history	Session images	limit, offset
search_images	Search all images	filters, sort_order

View Generation Tools →

Style Presets

Manage reusable style templates:

Tool	Purpose	Key Parameters
create_style_preset	Create preset	name, prompt, negative_prompt
list_style_presets	Browse presets	-
get_style_preset	Preset details	id/name
update_style_preset	Modify preset	id/name, updates
delete_style_preset	Remove preset	id/name

View Style Preset Tools →

Characters

Manage persistent character library:

Tool	Purpose	Key Parameters
create_character	Save character	character_name, base_prompt
update_character	Modify character	character_id/name, updates
delete_character	Remove character	character_id/name
list_characters	Browse library	search, sort_by, limit
get_character	Character details	character_id/name
get_character_video	Character video ref	character_id/name, format
refresh_character_identity	Regenerate identity references (background job)	character_id / character_ids / tag, options
get_character_identity_refresh_status	Poll a refresh job	job_id
revert_character_identity	Undo the last identity refresh	character_id
generate_with_character	Single character	character_id/name, scene_prompt
generate_with_multiple_characters	Multi-character	character_ids/names, scene_prompt

View Character Tools →

Products

Manage product references for marketing:

Tool	Purpose	Key Parameters
create_product_reference	Save product	product_name, product_url
list_product_references	Browse products	search, page, page_size
get_product_reference	Product details	id/product_name
update_product_reference	Update product	id/product_name, updates
delete_product_reference	Remove product	id/product_name
generate_with_product	Marketing images	product_id/name, scene_prompt

View Product Tools →

Reference Groups

Save and reuse sets of reference images:

Tool	Purpose	Key Parameters
create_reference_group	Create group	group_name, reference_image_ids
list_reference_groups	Browse groups	search, limit, offset, sort_by
get_reference_group	Group details	id/group_name
update_reference_group	Modify group	id/name, updates
delete_reference_group	Remove group	id/name

View Reference Group Tools →

Scenes

Save and reuse scene presets with prompts and reference images:

Tool	Purpose	Key Parameters
create_scene	Create preset	scene_name, scene_prompt, reference_image_ids
list_scenes	Browse presets	search, limit, offset, sort_by
get_scene	Scene details	scene_id/scene_name
update_scene	Modify preset	scene_id/name, updates
delete_scene	Remove preset	scene_id/scene_name

View Scene Tools →

Models & Analytics

Model discovery, usage tracking and documentation:

Tool	Purpose	Key Parameters
get_usage_stats	Usage statistics	granularity, lookback_days
get_account_summary	Account overview	-
list_models	Models and capabilities for your workspace	include_unavailable
check_quota	Pre-flight quota check	estimated_images
get_help	Tool documentation	tool_name, category, workflow

View Analytics Tools →

Common Parameters

Aspect Ratios

Available across generation tools:

Value	Ratio	Use Case
square	1:1	Social media, avatars
portrait	3:4	Mobile wallpapers
landscape	4:3	Desktop backgrounds
16:9	16:9	Widescreen, presentations
9:16	9:16	Stories, TikTok

Also supports numeric ratios like 2:3, 3:2, 4:5, 5:4, and 21:9 (see generate_image docs).

Model Selection

For generation tools:

Model	Description
gemini-flash-lite-image	Nano Banana 2 Lite — fastest, lowest-cost 1K model (default)
gemini-flash-image	Nano Banana 2 — broader ratios and 0.5K–4K tiers
gemini-pro-image	Go Bananas! Pro — highest Gemini quality, 1K/2K/4K
openai-gpt-image-2	OpenAI GPT Image 2 — text rendering, size/quality/format controls
openai-gpt-image-2.5-flare	OpenAI GPT Image 2.5 Flare — fast everyday generation, xhigh/max quality, transparent backgrounds
openai-gpt-image-2.5-sunburst	OpenAI GPT Image 2.5 Sunburst — precise generation and editing, same controls as Flare

Only models enabled for your workspace can be used; list_models shows which. See Generation Tools for the full comparison.

Pagination

For list tools:

Parameter	Type	Default	Max
limit	number	50	200
offset	number	0	-
page	number	1	-
page_size	number	20	100

Tool Response Patterns

Success Response

{
  "content": [
    {
      "type": "text",
      "text": "Operation completed successfully.\n\nDetails:\n- ID: 123\n- URL: https://..."
    }
  ]
}

Image Generation Response

{
  "content": [
    {
      "type": "text",
      "text": "Generated 1 image:\n\n**Image #342**\n- URL: https://pub-xxx.r2.dev/...\n- Thumbnail: https://pub-xxx.r2.dev/...-thumb.jpg\n- Dimensions: 1024x768\n- Size: 2.3 MB"
    }
  ]
}

List Response

{
  "content": [
    {
      "type": "text",
      "text": "Found 12 characters:\n\n1. Luna (45 uses)\n2. Captain Rex (23 uses)\n3. Felix (18 uses)\n...\n\nPage 1 of 2"
    }
  ]
}

Error Response

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Character 'Unknown' not found"
  }
}

Usage Tracking

All tool calls are tracked for analytics:

Field	Description
operation	Tool name
images_generated	Number of images
total_size_bytes	Storage used
duration_ms	Execution time
timestamp	When called

View your usage with get_usage_stats.

Rate Limiting

Tools are rate-limited per tenant:

Limit	Default	Customizable
Requests/minute	60	Yes
Concurrent	10	Yes
Images/request	4	No

When rate limited, tools return:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "retry_after": 30
    }
  }
}

Best Practices

1. Use Specific Tool Names

When asking Claude:

✅ "Use generate_with_character with Luna"
✅ "Search images from last week"

❌ "Make an image somehow"

2. Provide Clear Parameters

✅ "Generate a sunset, landscape aspect ratio, 2 images"
✅ "Create character named 'Max', friendly robot appearance"

❌ "Generate something nice"

3. Handle Errors Gracefully

Check for errors before proceeding:

If generation fails:
- Check error code
- Retry if rate limited
- Adjust prompt if content policy

4. Clean Up Unused Resources

Delete old characters when done
Remove unused style presets
Clean up test images

Tool Discovery

List All Tools

Claude Desktop and other MCP clients can discover tools:

const tools = await client.listTools();
// Returns all 53 tool definitions with schemas (54 through the STDIO proxy)

Get Help for a Tool

Use the get_help tool:

get_help({
  tool_name: "generate_image"
})

Returns detailed documentation, parameters, and examples.

Browse by Category

get_help({
  category: "characters"
})

Returns all character-related tools.

Next Steps

Explore each tool category:

• Generation Tools →
• Style Preset Tools →
• Character Tools →
• Product Tools →
• Reference Group Tools →
• Scene Tools →
• Analytics Tools →