Use Gemini in OpenCode via Vertex AI provider

Google prohibits third-party software (such as OpenCode, Hermes Agent, OpenClaw, etc), from using consumer OAuth tokens to access Gemini API, making subscription services like Google AI Pro and Ultra non usable with them. To safely use Gemini models in third-party software, there are two legitimate options:

  1. Google AI Studio (Pay-as-you-go): Add prepaid billing (min $10) at Google AI Studio and generate a commercial Gemini API key.
  2. GCP Service Account via Gemini Enterprise Agent Platform provider (former Vertex AI): Call the Gemini API via Google Cloud’s AI platform. This gives isolated billing, regional data control, postponed billing, and other benefits.

Here are the steps to create a GCP service account (a non-human identity that owns a downloadable JSON key), and how to configure OpenCode to use it to access Gemini models. Bonus points: the same approach works also in Hermes Agent, OpenClaw and other tools, and the Agent Platform provider makes available many more model to use, not only the ones from Google.

Setup a GCP Project

Step A: Create a GCP Project & enable billing

Screen to create a new project in Google Cloud Platform

Step B: Enable the Agent Platform API for the project

  • In the Google Cloud Console, ensure the project opencode-dev is selected in the upper left selector
  • Go to APIs & Services > Enabled APIs & Services (direct link)
  • Click + Enable APIs and services.
  • Search for Agent Platform API (direct link) and click Enable.

Step C: Create the Service Account

  • Go to IAM & Admin > Service Accounts.
  • Click + Create Service Account.
  • Set the service account name to opencode-laptop and description to Use OpenCode on my dev machine
  • Click Create and continue.
  • In the Grant this service account access to project section, use the filter box to search for aiplatform.user.
  • Select the role Agent Platform User (formerly Vertex AI User, roles/aiplatform.user).
  • Click Continue.
  • In the next step (Grant users access to this service account / Principals with access), leave all fields empty.
  • Click Done to finish creating the service account.

Step C: Create and download the Service Account JSON file

  • Go to IAM & Admin > Service Accounts.
  • From the list of Service Accounts, click on opencode-laptop, and then open the Keys tab.
  • Click Add Key > Create new key > select JSON > Create.
  • Save the file to ~/.config/opencode/opencode-devmachine.json
  • For additional security, restrict file permissions to 600 (only owner has read+write permission)
chmod 600 ~/.config/opencode/opencode-devmachine.json

Configure OpenCode

The instructions to configure OpenCode to use a Gemini Enterprise Agent Platform are under the “Vertex AI” section of the providers page.

Three environmental variables (2 mandatory, 1 optional) are required:

  • GOOGLE_APPLICATION_CREDENTIALS: stores the path of the Service Account JSON file
  • GOOGLE_CLOUD_PROJECT: store the cloud project for the service account
  • VERTEX_LOCATION (optional): The region for Vertex AI. The default is global

Set the variables with inline command execution

The easiest way is to launch OpenCode while setting the environmental variables:

GOOGLE_APPLICATION_CREDENTIALS=~/.config/opencode/opencode-devmachine.json GOOGLE_CLOUD_PROJECT=opencode-dev opencode

Remember to close the OpenCode Server before passing the environmental vars from the command line, otherwise the existing server won’t pick them up. It fires up the first time OpenCode is launched after a system reboot, and then remains in memory.

Set the variables permanently in the shell Environment

For Zsh (macOS):

cat << 'EOF' >> ~/.zshrc

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/opencode/opencode-devmachine.json"
export GOOGLE_CLOUD_PROJECT="opencode-dev"
EOF
source ~/.zshrc

For Bash (Linux):

cat << 'EOF' >> ~/.bashrc

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/opencode/opencode-devmachine.json"
export GOOGLE_CLOUD_PROJECT="opencode-dev"
EOF
source ~/.bashrc

Model selection in OpenCode

  • Once OpenCode is running, type /models and look for Gemini models (e.g. google-vertex/gemini-3.8-flash)

When OpenCode is NOT configured to use Gemini models, the command /models returns only the free models available by default.

Once Google Vertex AI provide is configured, Gemini models (and other models available on Google Model Garden) are added to the list:

Select one Gemini model and start using it.

Shell tools to improve productivity

I love working in the terminal. I’m not a shortcut wizard, I barely remember a few, but I still love working in the terminal. Here is the list of apps and configurations I made over time to improve my shell.

Bat

Need to read the content of a file? Bat helps with with syntax highlighting, line numbers, git integration, and many other options.

Colored logs

Reading log files is part of every dev life, but why not making the task simpler with syntax highlighting? Tailspin to the rescue. docker logs -f <containter_name> | tspin

Easier file searches

find is a powerful tool, but the syntax is quite complex for simple search tasks. fd makes search simpler as typing fd specs to find all files and directories containing the word specs in current dir and subdirs, case insensitive. Or fd -e md to search for all the files ending with a .md in current dir and subdirs.

List files and dirs

eza replaces ls with syntax highlighting and git status out of the box, the possibility to see files and dirs and a tree format, order files by different attributes (name is the default, but then size, extension, etc). eza -T generates a nice tree view of all files and subdirs in the current path.

eza output

With a simple alias l="eza -l" and alias lt="eza -lT" navigating the filesystem will be much easier!

Who is using disk space?

Wondering how the disk space is used? dust replaces du and make the discovery very easy. For example, dust -z 1G searches for all files and folder better than 1Gb in the current dir.

For a file-system level overview, duf

ncdu offers interactive browsing of directories, and the possibility to remove files and dirs on-the-fly.

Open WebUI and mcpo to use all kinds of MCP servers

The integration of the Model Context Protocol (MCP) servers within Open WebUI significantly extends its functionality, by allowing access to external capabilities. Open WebUI both leverage native support for MCP server offering the HTTP streamable format, and usage of the mcpo (MCP-to-OpenAPI proxy server) for broader compatibility.

This article explains how to configure MPCO to leverage all kinds of MCP servers: local via sdio, or remote via SSE (Server-Sent Events), or Streamable HTTP. While this other article explains native support of HTTP streamable MCP servers in Open WebUI (added at the end of Sept 2025).

What is MCP?

MCP is an open standard that functions as a universal communication bridge, connecting LLMs to external tools and data sources. This protocol enables AI assistants to access real-time information and perform tasks on a variety of different areas.

MCP servers communicate with clients (the LLMs) using three primary channels: stdio (standard input/output), SSE (Server-Sent Events), or Streamable HTTP.

Because of the core architecture of Open WebUI, which is a web-based, multi-tenant environment, not a local desktop process, and because long-lived stdio or SSE connections are difficult to maintain securely across users and sessions, Open WebUI team decided to create mcpo (MCP-to-OpenAPI proxy server) – an open-source proxy that translates stdio, SSE-based or streamable HTTP MCP servers into OpenAPI-compatible endpoints.

In addition, mcpo automatically discovers MCP tools dynamically, generates REST endpoints, and creates interactive, human-readable OpenAPI documentation accessible at http://localhost:8000/docs.

Configure a mcpo server

mcpo can run MCP servers written as npm packages via npx, python packages via uvx, and can also wrap calls to SSE or Streamable HTTP MCP servers.

When launched from the command line, it’s possible to specify both an MCP server mcpo will run, or a configuration file which defines the MCP servers it will manage, their exposed names, etc. The project page has a lot examples on how to configure the different servers.

This article will use docker compose to launch mcpo, and a configuration file to define the MCP servers to expose. A simple docker-compose.yaml file follows:

services:
  mcpo:
    container_name: mcpo
    image: ghcr.io/open-webui/mcpo:main
    restart: unless-stopped
    volumes:
      # Map your local config directory to /app/config inside MCPO container
      - /Volumes/Data/development/open-webui/volumes/mcpo:/app/config
    ports:
      - 8000:8000
    # Command to launch MCPO using the mounted config file, with hot-reload enabled
    command: --config /app/config/config.json --hot-reload

In this example, the configuration file is created under /Volumes/Data/development/open-webui/volumes/mcpo/config.json on the host running Docker, which maps to /app/config/config.json in the command line passed to mcpo.

Four MCP servers are exposed via mcpo using the following config file:

{
  "mcpServers": {
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    },
    "youtube-transcript": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jkawamoto/mcp-youtube-transcript",
        "mcp-youtube-transcript"
      ]
    },
    "open-meteo": {
      "command": "npx",
      "args": ["open-meteo-mcp-server"]
    }
    "coingecko": {
      "type": "streamable-http",
      "url": "https://mcp.api.coingecko.com/mcp"
  }
}

Easy to spot, the configurations to add to the config.json file uses the same format of Gemini CLI, Claude, Visual Studio, or other MCP server clients.

Once changed the configuration, it’s possible to check if they’re correct looking at the mcpo container logs, using docker logs -f mcpo command. For example:

2025-10-26 15:12:07,498 - INFO - Config file modified: /app/config/config.json
2025-10-26 15:12:08,011 - INFO - Adding servers: ['coingecko_mcp_streamable_http']
2025-10-26 15:12:10,158 - INFO - HTTP Request: POST https://mcp.api.coingecko.com/mcp "HTTP/1.1 200 OK"
2025-10-26 15:12:10,159 - INFO - Received session ID: 7a3c7019bf4ec1aaa7b213d017cd968ca1c609ee6bb5612622a0d4ad41b8579d
2025-10-26 15:12:10,162 - INFO - Negotiated protocol version: 2025-06-18
2025-10-26 15:12:10,736 - INFO - HTTP Request: POST https://mcp.api.coingecko.com/mcp "HTTP/1.1 202 Accepted"
2025-10-26 15:12:10,806 - INFO - HTTP Request: GET https://mcp.api.coingecko.com/mcp "HTTP/1.1 404 Not Found"
2025-10-26 15:12:11,204 - INFO - HTTP Request: POST https://mcp.api.coingecko.com/mcp "HTTP/1.1 200 OK"
2025-10-26 15:12:12,038 - INFO - Successfully connected to new server: 'coingecko'
2025-10-26 15:12:12,038 - INFO - Config reload completed successfully

Otherwise, an ERROR log instance will be present.

The list of the MCP servers exposed, and their docs (what the LLM sees) can be browsed at http://localhost:8000/docs.

Connect to mcpo in Open WebUI

There are two ways to connect to mcpo in Open WebUI: via a User Tool Server in the User Settings, and via a Global Tool Server in the Admin Settings.

  • User Tool Servers utilize the client-side (your browser) to make the connection.
    • Ideal for accessing highly specific, local, or private development endpoints on your machine, as the resource exposure is isolated only to your session.
    • It would be possible to launch an mcpo server instance on the local machine and connect to it, while having Open WebUI running on another, remote, server, which was not configured to use the MCP, and for which the user has no admin privileges.
    • For example, a filesystem MCP can access files accessible only from the local machine where mcpo runs, while the Open WebUI server doesn’t have access to them.
  • Global Tool Servers utilize the server-side (Open WebUI’s backend) to make the connection.
    • This means the tool must be reachable from the server environment, typically using internal Docker network names or the host alias (host.docker.internal). It’s also possible to access to a mcpo running on another server / remotely, and reachable by the Open WebUI host machines.
    • For example, a fileserver MCP can access files present on the server, and not accessible to the user.
    • It would be possible to configure authentication credential shared among all the Open WebUI users, like the same Bearer token or sessions.
    • Once configured on the Open WebUI server, the MCP could be made available to all the users.

Of course, distinctions from these two options fade away if both Open WebUI and mcpo are launched on the same local machine, used to connect to Open WebUI. But it’s important to keep this distinction in mind.

Each server exposed by mcpo has to be configured separately.

For configuring Global Tool Servers, using the time server as example:

  1. Navigate to Admin Panel -> Settings -> External Tools.
  2. Click “+“ (Add Connection).
  3. Set the Type to OpenAPI.
  4. Set the URL to http://host.docker.internal:8000/time
    • If Open WebUI and mcpo are in the same docker network, http://mcpo:8000/time can be used, assuming the mcpo image has the name mcpo, like in the docker compose file used above.
  5. Set OpenAPI Spec to URL, and openapi.json.
  6. Set Auth to None.
  7. Set ID to time_mcp_mcpo.
    • This is the string used in the logs to identity the MCP tool call.
  8. Set Name to Time MCP via mcpo.
    • This is the string used in the UI to configure the available tools and MCP servers for the model (see below).
  9. Set Description to Get the current time and date

For configuring User Tools Servers, instead:

  1. Navigate to Settings -> External Tools.
  2. Click “+“ (Add Connection).
  3. Set the URL to http://localhost:8000/time
    • localhost because the mcpo server is accessible from the browser user session using localhost, or 127.0.0.1 address.
    • http://host.docker.internal:8000/time or http://mcpo:8000/time won’t work, as they refer to docker-network specific addresses, which are not available in the browser user session of the local machine
  4. Set OpenAPI Spec to URL, and openapi.json.
  5. Set Auth to None.

The time MCP server is now available inside Open WebUI, with two different names: Time MCP via mcpo if configured as Global Tool Server, or mcp-time if configured as User Tool Server.

Create an agent which uses MCP

To be sure the MCP call is considered, and then executed, by the LLM, ensure the model has tools support, and that Function Calling parameter set to Native in the Advanced Params section of the model configuration.

Here an example to create a specialized agent to return the current time, using the MCP server.

  1. Navigate to Workspace -> Models -> New Model.
  2. Set Model Name to Qwen3-Assistant.
  3. Set Base Model to qwen3:8b.
    • Or any other model supporting tools calling
  4. Set Description to Return the current time.
  5. No need to set any System Prompt.
  6. Advanced Params -> Show.
    • Set Function Calling to Native.
  7. In the Tools, check Time MCP via mcpo or mcp-time.

Save and start chatting with the agent, for example asking What's the current time?. Here what the result could be, where the result of the time MCP is expanded for additional clarity:

Open WebUI chat window
Example of an Open WebUI agent using a local MCP time server exposed via mcpo

Open WebUI and native MCP integration

The integration of the Model Context Protocol (MCP) servers within Open WebUI significantly extends its functionality, by allowing access to external capabilities. Open WebUI both leverage native support for MCP server offering the HTTP streamable format, and usage of the mcpo (MCP-to-OpenAPI proxy server) for broader compatibility.

This article explains how to configure Open WebUI’s native support for remove MCP servers offering HTTP streamable capabilities. For a guide on how to configure MCPO to leverage all kinds of MCP servers: local via sdio, or remote via SSE (Server-Sent Events), or Streamable HTTP, please refer to this article.

What is MCP?

MCP is an open standard that functions as a universal communication bridge, connecting LLMs to external tools and data sources. This protocol enables AI assistants to access real-time information and perform tasks on a variety of different areas.

MCP servers communicate with clients (the LLMs) using three primary channels: stdio (standard input/output), SSE (Server-Sent Events), or Streamable HTTP.

Connect to MCP via HTTP Streaming

In v0.6.31 Open WebUI added MCP (streamable HTTP) server support, alongside existing OpenAPI server integration. This allows to connect directly to an MCP server that exposes its functionality over a streaming HTTP endpoint. It supports Bearer token, session and OAuth for authentication, if necessary (doc page, but very basic so far).

To find MCP servers, the “Remote MCP Servers” page of Awesome MCP Servers is a good starting point. Looking at all the servers with http support, let’s user the one from CoinGecko.

Once logged in Open WebUI:

  1. Navigate to Admin Panel -> Settings -> External Tools.
  2. Click “+“ (Add Connection).
  3. Set the Type to MCP Streamable HTTP.
  4. Set the URL to https://mcp.api.coingecko.com/mcp
  5. Set Auth to None.
  6. Set ID to coingecko_mcp_http.
    • This is the string used in the logs to identity the MCP tool call.
  7. Set Name to CoinGecko MCP via http.
    • This is the string used in the UI to configure the available tools and MCP servers for the model (see below).

Create an agent which uses MCP

To be sure the MCP call is considered, and then executed, by the LLM, ensure the model has tools support, and that Function Calling parameter set to Native in the Advanced Params section of the model configuration.

Here an example to create a specialized agent to return values of crypto assets:

  1. Navigate to Workspace -> Models -> New Model.
  2. Set Model Name to Crypto expert.
  3. Set Base Model to qwen3:8b.
    • Or any other model supporting tools calling
  4. Set Description to Return value of crypto assets.
  5. Set System Prompt to You are a cryptocurrency price lookup agent. When the user specifies one or more cryptocurrency names (e.g., "bitcoin", "ethereum", "BTC", "CRO"), output ONLY the current market price in USD for each, formatted as: [Name]: $[price]. Do not add explanations, context, errors, or any text beyond this. If a crypto is unrecognized, output: [Name]: Not found.
  6. Advanced Params -> Show.
    • Set Function Calling to Native.
  7. In the Tools, check CoinGecko MCP via http.
  8. In the Capabilities, uncheck everything except Status Updates.

Save and start chatting with the agent, for example asking BNB price. Here what the result could be, where the result of the CoinGecko MCP is expanded for additional clarity:

Open WebUI chat window
Example of an Open WebUI agent using MCP server calls

If the MCP server doesn’t support streamable HTTP, it’s possible to use mcpo to access them.

“Servant leader” – Interview with Alfredo Morresi

[…] It was during that period that I met Alfredo Morresi, who even then was the community manager for developers. Ensoul was developing a prototype of a webVR viewer, and Alfredo immediately stood out for his kindness and attentiveness. Among other things, we were fortunate to receive an early physical prototype of the Google Pixel and an invitation to the Google VR Workshop in London. […]

Link to the original post, and thanks Fulvio for the interview!