A Practical Guide to Using NanoBanana MCP in OpenCode

A Practical Guide to Using NanoBanana MCP in OpenCode

If you already use OpenCode as a terminal-first coding agent, the annoying part of image work is usually not the prompt itself. It is the context switching: open a browser, upload references, copy URLs, try to keep product and model identity consistent, then bring the result back into your project. NanoBanana MCP gives OpenCode a remote image-generation and image-editing capability that can be called from the same terminal workflow.

What you can do

The documented NanoBanana MCP setup focuses on practical image workflows where references matter. The main scenarios are:

  • Multi-image composition: combine a product image and a scene image while keeping lighting consistent.
  • Virtual try-on style editing: ask the model image to wear a referenced clothing item while keeping the face and pose unchanged.
  • Product background changes: place an existing product into a more suitable environment.
  • Page illustrations: generate supporting visuals, such as a custom 404 illustration, directly while working in a project.

The MCP server exposes two main tools in the documentation: nanobanana_generate_image for text-to-image generation and nanobanana_edit_image for image editing with multiple image inputs. That split is useful: you can use generation for a fresh illustration, and editing when you need to preserve an existing subject, product, pose, or scene reference.

How it works

OpenCode reads MCP server configuration from an opencode.json file. The NanoBanana MCP server is remote, so OpenCode does not need a local image service running on your machine. Instead, it calls the hosted MCP endpoint:

https://nanobanana.mcp.acedata.cloud/mcp

Authentication is handled with an Ace Data Cloud API token passed as a Bearer token. The important detail is that this MCP server uses Bearer Token authentication, not OAuth. In OpenCode configuration, oauth must be explicitly set to false. If it is omitted, OpenCode may treat a 401 response as an OAuth challenge, which can surface as SSE error: Non-200 status code (401) when you run opencode mcp list.

Configure the token safely

Start by exporting your Ace Data Cloud token into the shell environment. Do not paste the real token into a repository, screenshot, issue, or public chat log.

export ACEDATACLOUD_API_KEY="replace with your real token"

OpenCode can then resolve the token through the {env:ACEDATACLOUD_API_KEY} placeholder. This is safer than writing a secret directly into opencode.json.

If your token lives in a .env file but has not been exported into the current shell process, use:

set -a && source .env && set +a

Without that step, OpenCode may show an empty authorization value such as "Authorization": "Bearer " in debug output because the environment placeholder was not resolved.

Choose global or project-level configuration

The same configuration shape works in two places. Use the global file if you want NanoBanana available from all projects:

~/.config/opencode/opencode.json

Use a project-level file if only one repository needs this MCP server:

opencode.json

A project-level opencode.json overrides the global configuration, which is helpful for team-specific setup or temporary experiments.

The OpenCode configuration

Here is the documented configuration pattern for NanoBanana MCP:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nanobanana": {
      "type": "remote",
      "url": "https://nanobanana.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

The fields are intentionally small:

  • type is remote, because OpenCode is connecting to a hosted MCP server.
  • url points to the NanoBanana MCP endpoint.
  • enabled controls whether this MCP entry is active.
  • oauth is false, so OpenCode sends the Bearer token directly.
  • headers.Authorization passes Bearer {env:ACEDATACLOUD_API_KEY}.

Verify the connection

After saving the config, ask OpenCode to list and debug MCP servers:

opencode mcp list
opencode mcp debug nanobanana

A successful handshake shows nanobanana connected. If it fails, check three things before changing anything else: the environment variable is exported, oauth is explicitly false, and the authorization header includes the Bearer prefix.

You can also inspect the current MCP tool list directly with JSON-RPC:

curl -X POST https://nanobanana.mcp.acedata.cloud/mcp   -H 'Authorization: Bearer <token>'   -H 'Accept: application/json'   -H 'Content-Type: application/json'   --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Use it inside a builder workflow

Once connected, you do not need to switch into a special MCP panel. The documented workflow is to call NanoBanana naturally from an OpenCode session. For example, while building an e-commerce page, you might ask OpenCode:

Change this model image to wear this piece of clothing (link xxx), keeping the face and pose unchanged.

Or, for a product landing page:

Put this product image (link A) into this scene image (link B), keeping the lighting consistent.

This is where the setup becomes useful in daily work. The image task lives next to the code task: update a page, generate a fitting visual, paste the resulting asset URL into the README or UI, and keep moving.

Closing notes

The small but important part of this setup is not the image model name; it is the workflow boundary. By putting NanoBanana behind a remote MCP server, OpenCode can treat image generation and multi-reference editing as callable tools inside the terminal. Start with a project-level config, verify opencode mcp list, then move it to the global config only after it works reliably.

For the original setup details, see the Ace Data Cloud documentation: OpenCode with Nano Banana MCP.

Comments

Post a Comment

Popular posts from this blog

Artistic QR Code API Integration Guidance

Image
Artistic QR code is an innovative technological product that combines QR codes with beautiful background images, creating practical and visually appealing works. They not only possess the functionality of traditional QR codes, allowing quick scanning and recognition by smart devices, but also incorporate artistic elements to enhance visual appeal and brand recognition. Some artistic QR codes are even generated by artificial intelligence, fully leveraging modern technology to demonstrate unparalleled innovation and uniqueness. This makes artistic QR codes widely applicable in areas such as brand marketing and advertising. In simple terms, artistic QR codes are the perfect combination of QR code scanning and artistic aesthetics. They not only provide the function of information transmission, but also enhance the user's visual experience, making each scan a delightful artistic enjoyment. Overview of Artworks Let's take a look at a few QR code works: How are they? These are ar...
Read more

How to Configure Claude Code with CC Switch and Ace Data Cloud

Image
If you use Claude Code across a terminal, VS Code, or remote development setup, the awkward part is often not the model itself but the configuration: where should requests go, where should the token live, and how do you switch providers without editing files by hand? This guide walks through a practical setup using CC Switch as the graphical configuration manager and Ace Data Cloud as the Anthropic-compatible base URL. The goal is simple: configure Claude Code once, verify the active endpoint, and keep the setup easy to change later. What you can do With the setup described in the Ace Data Cloud documentation, you can: Manage Claude Code provider configuration through a desktop UI instead of manually editing settings.json . Store an Ace Data Cloud provider with ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN . Switch the active Claude Code provider from CC Switch without rewriting your configuration every time. Use the same provider configuration from the terminal an...
Read more

How to Build a Server-Side Image Editing Workflow with GPT-Image-2

Image
If your product needs image editing, the hard part is rarely the model call itself. The real challenge is building a reliable workflow around user images, reference assets, predictable output sizes, and slow-running jobs without forcing every file through a manual upload step. This guide walks through a practical server-side workflow using the OpenAI Images Edits API on Ace Data Cloud. The focus is gpt-image-2 , because the documented editing flow supports direct image URLs, base64 input, multiple reference images, high-resolution output through size , and asynchronous callbacks. What you can do The edits endpoint is designed for turning one or more input images plus an instruction into a modified output image. In practical terms, you can use it to: Convert an existing infographic or poster into a different visual theme while preserving its layout. Change a product, shelf, room, or object style while keeping the original arrangement stable. Pass image URLs directly f...
Read more