FAQ

Frequently asked questions about Go Bananas!.

General Questions

What is Go Bananas!?

Go Bananas! is a production-ready, multi-tenant MCP (Model Context Protocol) server for AI image generation. It runs on Cloudflare's edge network and supports multiple image-generation backends: Google's Gemini (Flash + Pro) and OpenAI gpt-image-2 — picked per request via model_id.

What can I do with Go Bananas!?

• Generate images from text prompts
• Edit images conversationally
• Maintain consistent characters across scenes
• Create product marketing images
• Save and apply style presets
• Track usage and analytics

What AI models does it use?

Go Bananas! ships with six image-generation models registered in src/models/registry.ts:

• Nano Banana 2 Lite (gemini-flash-lite-image) — Fastest, lowest-cost 1K model, default for new tenants
• Nano Banana 2 (gemini-flash-image) — Versatile Flash image model with 2K/4K tiers and stronger multi-reference workflows
• Go Bananas! Pro (gemini-pro-image) — Higher Gemini quality, 4K tiers, Google Search grounding
• OpenAI gpt-image-2 (openai-gpt-image-2) — Best-in-class text rendering, quality tiers (low/medium/high), JPEG/WebP output
• OpenAI GPT Image 2.5 Flare (openai-gpt-image-2.5-flare) — Fast everyday generation; adds xhigh/max quality and transparent backgrounds
• OpenAI GPT Image 2.5 Sunburst (openai-gpt-image-2.5-sunburst) — Precise generation and editing, with the same controls as Flare

Tenants pick which models they can route to via the allowed_models allowlist; per-request override via model_id.

Do I need a Gemini API key?

You need at least one provider key — Gemini, OpenAI, or both. Each tenant can store up to five keys per provider. Go Bananas rotates the starting key between requests and automatically tries the next key when a provider reports an authentication, quota, or rate-limit failure. Provider pools are encrypted independently in tenant_provider_credentials (AES-GCM), so you can replace or remove one provider without touching the other.

• Gemini: get a key at Google AI Studio.
• OpenAI: get a key at platform.openai.com. gpt-image-2 requires API Organization Verification.

MCP & Integration

What is MCP?

MCP (Model Context Protocol) is an open protocol that allows AI models like Claude to use external tools. Go Bananas! implements an MCP server that exposes 47 image generation and management tools.

How do I connect to Go Bananas!?

Use remote HTTP OAuth when your client supports it; use the local STDIO proxy for clients that need a command-based MCP server. Do not mix both modes under the same go-bananas server name/scope.

Claude Code (remote HTTP OAuth):

claude mcp add --transport http -s user go-bananas https://mcp.gobananasai.com

Codex (remote HTTP OAuth):

codex mcp add go-bananas --url https://mcp.gobananasai.com
codex mcp login go-bananas

Claude Desktop / Cursor STDIO proxy:

Run npx -y gobananas-cli auth login, then configure:

{
  "mcpServers": {
    "go-bananas": {
      "command": "npx",
      "args": ["-y", "gobananas-mcp"],
      "env": {
        "GO_BANANAS_SERVER_URL": "https://gobananasai.com",
        "GO_BANANAS_MCP_TRANSPORT": "streamable-http"
      }
    }
  }
}

For CI or headless setups, add GO_BANANAS_API_KEY to the same env object.

Does it work with Cursor/other editors?

Yes. Clients with remote HTTP MCP OAuth can connect directly to https://mcp.gobananasai.com. Clients without that support can launch gobananas-mcp and authenticate through local CLI tokens or an API key.

What's the difference between SSE and HTTP transport?

• SSE (Server-Sent Events) - Legacy transport at /sse
• Streamable HTTP - Recommended transport at /mcp; supports stateless MCP 2026-07-28 plus legacy client fallback

Both work, but HTTP is preferred for new integrations. MCP 2026 transport requests are stateless; Go Bananas editing continuity uses an explicit application session_id.

Image Generation

What image formats are supported?

Generated images are PNG by default. You can upload JPEG, PNG, WebP or single-frame GIF images for editing, up to 20 MB and 4,194,304 total pixels (about 4.2 megapixels). Resize larger images and export animated GIFs as one frame first. When using openai-gpt-image-2, set output_format to jpeg or webp to get smaller files (use output_compression to tune size 0–100).

What's the maximum prompt length?

• Gemini Flash: 16,384 characters
• Gemini Pro: 16,384 characters
• OpenAI gpt-image-2: 32,000 characters

Can I generate multiple images at once?

Yes! Set n parameter from 1-4 to generate multiple variations:

{
  "prompt": "A sunset over mountains",
  "n": 4
}

Why was my image blocked?

Google's safety filters may block certain content. Try:

• Modifying the prompt to be less ambiguous
• Adding negative prompts to exclude problematic elements
• Reviewing Google's content policies

How do I improve image quality?

1. Use more detailed prompts
2. Specify style, lighting, composition
3. Use negative prompts to exclude unwanted elements
4. Try Gemini Pro for complex scenes that need 4K output or Google Search grounding
5. Try OpenAI gpt-image-2 (quality: "high") for text-heavy compositions and infographics
6. Use reference images for style guidance

Characters & Products

What are characters?

Characters are saved visual identities that can be reused across multiple sessions. They include:

• Base prompt (appearance description)
• Reference images (optional)
• Style preferences

How many reference images should I use?

2-3 reference images typically work best. They help maintain visual consistency without overwhelming the model.

Can I use characters across sessions?

Yes! Characters are stored in the database and persist across sessions. This is the main benefit of the character system.

What are product references?

Product references let you save a product image and generate unlimited marketing scenes featuring that product consistently.

How do I keep characters consistent?

1. Create detailed base prompts
2. Add reference images
3. Avoid scene elements in base prompts
4. Use consistent style presets

Sessions & Editing

What is a session?

A Go Bananas application session groups related image operations together and tracks the last generated or edited image. It is identified by the session_id tool argument and is separate from MCP transport state. The CLI and stdio proxy add their persisted application session ID to session-aware tools automatically.

What is conversational editing?

The ability to edit images naturally, like "add clouds" or "make it brighter", without specifying which image to edit. The system automatically uses the last image in your session.

How do I edit a specific image?

Use the edit_image tool with the image ID:

{
  "image_id": 42,
  "prompt": "Add a rainbow"
}

How do I see edit history?

Use get_image_info to see an image's edit lineage, including parent image and edit depth.

API & Authentication

How do I get an API key?

Contact your administrator or use the admin API to create one:

curl -X POST /admin/tenants/{id}/api-keys \
  -H "X-Admin-Token: xxx" \
  -d '{"label": "My Key"}'

What's the difference between live and test keys?

• sk_live_* - Production keys, full access
• sk_test_* - Test keys, same access (for development)

Both work identically; the prefix is for organizational purposes.

How do I rotate API keys?

1. Create a new key via admin API
2. Update your applications
3. Revoke the old key

What rate limits apply?

Default limits per tenant:

• 60 requests per minute
• 10 GB monthly storage

Limits can be customized per tenant.

Self-Hosting

Can I self-host Go Bananas!?

Yes! Go Bananas! is designed for self-hosting on Cloudflare:

git clone https://github.com/davendra/go-bananas-app.git
cd go-bananas-app
npm install
npm run deploy

What Cloudflare services are required?

• Workers - Compute
• D1 - Database
• R2 - Image storage
• KV - Configuration cache
• Durable Objects - Session state

How much does hosting cost?

Cloudflare offers generous free tiers:

• Workers: 100,000 requests/day free
• D1: 5 GB storage free
• R2: 10 GB storage free

Production costs scale with usage. See Cloudflare pricing for details.

Can I use a different database?

D1 is tightly integrated. Using a different database would require significant modifications to the storage layer.

Troubleshooting

"Invalid or missing API key"

1. Check key format (should be sk_live_* or sk_test_*)
2. Verify key exists in database
3. Check key is active (not revoked)
4. Ensure header is X-API-Key

"Rate limit exceeded"

Wait for the cooldown period or contact admin to increase limits. Check the Retry-After header.

"Image generation failed"

1. Verify Gemini API key is valid
2. Check prompt for policy violations
3. Review Go Bananas! logs
4. Test Gemini API directly

"Character not found"

1. Verify character exists for your tenant
2. Check character ID/name is correct
3. Ensure you're using the right API key (same tenant)

Images look inconsistent

1. Add more reference images to character
2. Improve base prompt with specific details
3. Use style presets for consistency
4. Avoid conflicting scene descriptions

Getting Help

Where can I report bugs?

GitHub Issues

Where can I request features?

GitHub Discussions

Is there a community?

Join discussions on GitHub or check the repository for community links.

Next Steps

• Glossary →
• Troubleshooting →
• API Reference →