MCP Development with Zig, Cloud Run, and Gemini CLI

--- title: MCP Development with Zig, Cloud Run, and Gemini CLI published: true series: MCP-Cloudrun date: 2026-02-01 23:46:02 UTC tags: googlecloudrun,zig,aiagent,mcps canonical_url: https://xbill999.medium.com/mcp-development-with-zig-cloud-run-and-gemini-cli-2fe34586ac4b --- Leveraging Gemini CLI and the underlying Gemini LLM to build Model Context Protocol (MCP) AI applications in the Zig programming language deployed to Google Cloud Run.  #### Why not just use Python? Python has traditionally been the main coding language for ML and AI tools. One of the strengths of the MCP protocol is that the actual implementation details are independent of the development language. The reality is that not every project is coded in Python- and MCP allows you to use the latest AI approaches with other coding languages. #### Zig? Are you just inventing languages now? The goal of this article is to provide a minimal viable basic working MCP stdio server in Zig that can be run locally without any unneeded extra code or extensions. The ZigMCP library is here: [GitHub - muhammad-fiaz/mcp.zig: A comprehensive Model Context Protocol (MCP) library for Zig - bringing MCP support to the Zig ecosystem.](https://github.com/muhammad-fiaz/mcp.zig) #### What Is Zig? Zig is a modern, open-source, general-purpose systems programming language and toolchain designed for robustness, optimality, and clarity. Created by Andrew Kelley, it aims to be a “better C,” offering manual memory management, no hidden allocations, and powerful compile-time code execution (comptime). Zig also functions as a C/C++ compiler and build system. The main site for Zig is here: [Home ⚡ Zig Programming Language](https://ziglang.org/) #### Installing Zig The step by step instructions vary by platform. Here is a site with starter steps for a Debian based system: [How to Install Zig on Debian: The Easy Way with debian.griffo.io](https://dario.griffo.io/posts/how-to-install-zig-debian#:~:text=This%20design%20allows%20you%20to,Multiple%20Versions%20with%20update%2Dalternatives) #### Gemini CLI If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance: ``` npm install -g @google/gemini-cli ``` #### Testing the Gemini CLI Environment Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account: ``` gemini ```  #### Node Version Management Gemini CLI needs a consistent, up to date version of Node. The **nvm** command can be used to get a standard Node environment: [GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions](https://github.com/nvm-sh/nvm) #### Zig MCP Documentation This Zig MCP page provides samples and documentation for getting started: [mcp.zig | Model Context Protocol for Zig](https://muhammad-fiaz.github.io/mcp.zig/) #### Where do I start? The strategy for starting MCP development is a incremental step by step approach. First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration. Then, a minimal Hello World Style Zig MCP Server is built with HTTP transport. This server is validated with Gemini CLI in the local environment. This setup validates the connection from Gemini CLI to the local process via MCP. The MCP client (Gemini CLI) and the MCP server both run in the same local environment. Next- the basic MCP server is wrapped in a container and deployed remotely to Google Cloud Run. This remote MCP server running on a Cloud Run endpoint is validated with a local copy of Gemini CLI. #### Setup the Basic Environment At this point you should have a working Zig build environment and a working Gemini CLI installation. The next step is to clone the GitHub samples repository with support scripts: ``` cd ~ git clone https://github.com/xbill9/gemini-cli-codeassist ``` Then run **init.sh** from the cloned directory. The script will attempt to determine your shell environment and set the correct variables: ``` cd gemini-cli-codeassist source init.sh ``` If your session times out or you need to re-authenticate- you can run the **set\_env.sh** script to reset your environment variables: ``` cd gemini-cli-codeassist source set_env.sh ``` Variables like PROJECT\_ID need to be setup for use in the various build scripts- so the set\_env script can be used to reset the environment if you time-out. #### Hello World with HTTP Transport One of the key features that the standard MCP libraries provide is abstracting various transport methods. The high level MCP tool implementation is the same no matter what low level transport channel/method that the MCP Client uses to connect to a MCP Server. The simplest transport that the SDK supports is the stdio (stdio/stdout) transport — which connects a locally running process. Both the MCP client and MCP Server must be running in the same environment. The HTTP transport allows the MCP client and server to run in the same environment or deployed remotely over the Internet. The connection over HTTP will look similar to this: ``` logInfo("Server starting on 0.0.0.0:8080..."); var http_transport = try HttpServerTransport.init(allocator, 8080); defer http_transport.deinit(); try server.runWithTransport(http_transport.transport()); ``` #### Zig Package Information The code depends on several standard Ziglibraries for MCP and logging: ``` const std = @import("std"); const mcp = @import("mcp"); ``` #### Installing and Running the Zig Code Run the install make release target on the local system: ``` xbill@penguin:~/gemini-cli-codeassist/mcp-https-zig$ make zig build Linked zig-out/bin/mcp-https-zig to server ``` To lint the code: ``` xbill@penguin:~/gemini-cli-codeassist/mcp-https-zig$ make lint zig fmt --check . zig build -Doptimize=ReleaseFast ``` To test the code: ``` xbill@penguin:~/gemini-cli-codeassist/mcp-https-zig$ make test zig build Linked zig-out/bin/mcp-https-zig to server zig build test python3 test_server.py Testing server tools (HTTP)... ✓ initialize ✓ notifications/initialized ✓ tools/list ✓ tools/call (greet) All tests passed! ``` #### Gemini CLI settings.json In this example — the C source code uses a compiled binary that can be called directly from Gemini CLI. The default Gemini CLI settings.json has an entry for the source: ``` { "mcpServers": { "mcp-https-zig": { "httpUrl": "http://127.0.0.1:8080/mcp" } } } ``` #### Start the Local MCP Server Open a terminal window and kick off the local MCP server: ``` xbill@penguin:~/gemini-cli-codeassist/mcp-https-zig$ make run zig build Linked zig-out/bin/mcp-https-zig to server ./server {"asctime":"1769988227","name":"root","levelname":"INFO","message":"Server starting on 0.0.0.0:8080..."} ``` #### Validation with Gemini CLI Next- open another window and start Gemini CLI. The local MCP connection over HTTP to the Zig Code is validated and the full Gemini CLI session will start: ``` > /mcp schema Configured MCP servers: 🟢 mcp-https-zig - Ready (1 tool) Tools: - greet Get a greeting from a local http server. Parameters: { "type": "object" } > /mcp list Configured MCP servers: 🟢 mcp-https-zig - Ready (1 tool) Tools: - greet > greet Carmen the Gator! ✦ I will read src/main.zig to understand the greet tool's implementation and parameters. ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ ReadFile src/main.zig │ │ │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ I will call the greet tool with the argument "Carmen the Gator!". ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ? greet (mcp-https-zig MCP Server) {"param":"Carmen the Gator!"} ← │ │ │ │ MCP Server: mcp-https-zig │ │ Tool: greet │ │ │ │ Allow execution of MCP tool "greet" from server "mcp-https-zig"? │ │ │ │ 1. Allow once │ │ 2. Allow tool for this session │ │ 3. Allow all server tools for this session │ │ ● 4. Allow tool for all future sessions │ │ 5. No, suggest changes (esc) │ │ │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ I will call the greet tool with the argument "Carmen the Gator!". ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ greet (mcp-https-zig MCP Server) {"param":"Carmen the Gator!"} │ │ │ │ Carmen the Gator! │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` #### Deploying to Cloud Run After the HTTP version of the MCP server has been tested locally — it can be deployed remotely to Google Cloud Run. First- switch to the directory with the HTTP MCP sample code: ``` cd ~/gemini-cli-codeassist/mcp-https-zig ``` Deploy the project to Google Cloud Run with the pre-built **cloudbuild.yaml** and **Dockerfile:** ``` cd ~/gemini-cli-codeassist/mcp-https-zig xbill@penguin:~/gemini-cli-codeassist/mcp-https-zig$ make deploy ``` The Cloud Build will start: ``` Step #0: Step 2/12 : RUN apt-get update && apt-get install -y curl xz-utils git && rm -rf /var/lib/apt/lists/* │ │ Step #0: ---> Running in 30866bbb7eec │ │ Step #0: Get:1 http://deb.debian.org/debian bookworm InRelease [151 kB] │ │ Step #0: Get:2 http://deb.debian.org/debian bookworm-updates InRelease [55.4 kB] │ │ Step #0: Get:3 http://deb.debian.org/debian-security bookworm-security InRelease [48.0 kB] │ │ Step #0: Get:4 http://deb.debian.org/debian bookworm/main amd64 Packages [8792 kB] │ │ Step #0: Get:5 http://deb.debian.org/debian bookworm-updates/main amd64 Packages [6924 B] │ │ Step #0: Get:6 http://deb.debian.org/debian-security bookworm-security/main amd64 Packages [293 kB] │ │ Step #0: Fetched 9346 kB in 2s (5971 kB/s) │ ``` **It can take 15–30 minutes to complete the build.** The cloud build needs to pull in all the Zig libraries in the build environment and generate the entire package from scratch: ``` Starting Step #1 Step #1: Already have image (with digest): gcr.io/cloud-builders/gcloud Step #1: Deploying container to Cloud Run service [mcp-https-zig] in project [comglitn] region [us-central1] Step #1: Deploying... Step #1: Setting IAM Policy..............done Step #1: Creating Revision..............................................done Step #1: Routing traffic.....done Step #1: Done. Step #1: Service [mcp-https-zig] revision [mcp-https-zig-00006-drl] has been deployed and is serving 100 percent of traffic. Step #1: Service URL: https://mcp-https-zig-1056842563084.us-central1.run.app Finished Step #1 PUSH DONE ``` When the build is complete- an endpoint will be returned. The service endpoint in this example is : ``` https://mcp-https-zig-1056842563084.us-central1.run.app ``` The actual endpoint will vary based on your project settings. #### Review Service in Cloud Run Navigate to the Google Cloud console and search for Cloud Run -  and then you can detailed information on the Cloud Run Service:  #### Cloud Logging The remote server writes logs to **stderr** in standard JSON format. These logs are available from the deployed Cloud Run Service:  #### Validate HTTP connection Once you have the Endpoint — you can attempt a connection- navigate to in your browser: ``` https://mcp-https-zig-1056842563084.us-central1.run.app ``` You will need to adjust the exact URL to match the URL returned from Cloud Build. You will get an error- this connection is expecting a message in the MCP format: ``` Page Not Found ``` #### Gemini CLI settings.json.cloudrun Replace the default Gemini CLI configuration file —  **settings.json** with a pre-configured sample- **settings.json.cloudrun** to use the Cloud Run version of the connection: ``` { "mcpServers": { "mcp-cloudrun-zig": { "httpUrl": "https://mcp-https-zig-1056842563084.us-central1.run.app/mcp" } } } ``` Copy the Cloud Run version of the Gemini CLI configuration file: ``` xbill@penguin:~/gemini-cli-codeassist/mcp-https-zig$ cd .gemini cp settings.json.cloudrun settings.json xbill@penguin:~/gemini-cli-codeassist/mcp-https-zig/.gemini$ ``` #### Validation with Gemini CLI The final connection test uses Gemini CLI as a MCP client with the deployed Cloud Run Service in Zig providing the MCP server. Startup Gemini CLI with the updated settings : ``` gemini > /mcp list Configured MCP servers: 🟢 mcp-cloudrun-zig - Ready (1 tool) Tools: - greet > greet Carmen the Zig Mascot ✦ I will read the src/main.zig file to understand the greet tool's implementation and parameter requirements. ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ ReadFile src/main.zig │ │ │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ I will call the greet tool with the parameter param set to "Carmen the Zig Mascot". ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ? greet (mcp-cloudrun-zig MCP Server) {"param":"Carmen the Zig Mascot"} ← │ │ │ │ MCP Server: mcp-cloudrun-zig │ │ Tool: greet │ │ │ │ Allow execution of MCP tool "greet" from server "mcp-cloudrun-zig"? │ │ │ │ 1. Allow once │ │ 2. Allow tool for this session │ │ 3. Allow all server tools for this session │ │ ● 4. Allow tool for all future sessions │ │ 5. No, suggest changes (esc) │ │ │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ I will call the greet tool with the parameter param set to "Carmen the Zig Mascot". ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ greet (mcp-cloudrun-zig MCP Server) {"param":"Carmen the Zig Mascot"} │ │ │ │ Carmen the Zig Mascot │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ Carmen the Zig Mascot ``` #### Code Review the Zig Project Gemini CLI is used to review the Zig Project: ``` > what does the project do? ✦ This project is a Model Context Protocol (MCP) server written in Zig. Here is a breakdown of its functionality: * MCP Server: It implements the MCP specification, allowing AI assistants (like Claude or Gemini) to connect to it and use its tools. * HTTP Transport: Unlike many MCP servers that use standard input/output (stdio), this server listens on HTTP port 8080 for JSON-RPC 2.0 messages. * Tools: It currently exposes a single tool named greet, which takes a name as a parameter and returns it. * Logging: It outputs structured JSON logs to stderr. Essentially, it's a lightweight, network-accessible server that provides a "hello world" style capability for AI agents via the MCP standard. ``` #### Summary MCP development with Zig using Gemini CLI was validated with an incremental step by step approach. A minimal streaming HTTP transport MCP Server was built from source code and validated with Gemini CLI running as a MCP client in the same local environment. Then — the MCP server was wrapped in a container and submitted to Google Cloud Build for deployment to Google Cloud Run. The remote MCP server was validated with a standard browser, and Gemini CLI. Finally- remote MCP operations were performed from the local Gemini CLI installation to the Zig MCP server hosted in Google Cloud Run. This approach can be extended to more complex deployments and Cloud based options.