MCP Development with Python, and Azure Kubernates Service (AKS)

--- title: MCP Development with Python, and Azure Kubernates Service (AKS) published: true series: Azure date: 2026-04-03 18:59:56 UTC tags: geminicli,mcpserver,python,ak canonical_url: https://xbill999.medium.com/mcp-development-with-python-and-azure-kubernates-service-aks-c35a12b89b50 --- Leveraging Gemini CLI and the underlying Gemini LLM to build Model Context Protocol (MCP) AI applications with Python with a local development environment deployed to the Azure Kubernates Service.  #### What is Gemini CLI? The Gemini CLI is an open-source, terminal-based AI agent from Google that allows developers to interact directly with Gemini models, such as Gemini 2.5 Pro, for coding, content creation, and workflow automation. It supports file operations, shell commands, and connects to external tools via the Model Context Protocol (MCP). The full details on Gemini CLI are available here: [Build, debug & deploy with AI](https://geminicli.com/) #### Azure Kubernates Service Azure Kubernetes Service (AKS) is a fully managed, serverless Kubernetes service on Microsoft Azure that simplifies deploying, scaling, and managing containerized applications. It handles critical tasks like health monitoring, maintenance, and automated upgrades, reducing operational complexity. AKS is used for microservices, DevOps, and cloud-native app development. More details are available here: [https://azure.microsoft.com/en-us/products/kubernetes-service](https://azure.microsoft.com/en-us/products/kubernetes-service)  #### Isn’t that Overkill? A whole Cluster Just for some MCP?! An entire cluster is a large deployment for just a basic MCP server. The goal was to validate that MCP servers could be deployed — and that opens the door for more complex deployments that can take advantage of the full services in the cluster. #### Why would I want Gemini CLI with Azure? Isn’t that a Google Thing? Yes- Gemini CLI leverages the Google Cloud console and Gemini models but it is also open source and platform agnostic. Many applications are already cross-cloud so this enables familiar tools to be run natively on Microsoft Azure. #### 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) #### Gemini CLI Installation You can then download the Gemini CLI : ```shell 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: ```shell gemini ``` #### Authentication Several authentication options are available. To use an existing Code Assist licence — authenticate with a Google Account: ```plaintext > /auth ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ ? Get started │ │ │ │ How would you like to authenticate for this project? │ │ │ │ ● 1. Login with Google │ │ 2. Use Gemini API Key │ │ 3. Vertex AI │ │ │ │ (Use Enter to select) │ │ │ │ Terms of Services and Privacy Notice for Gemini CLI │ │ │ │ https://geminicli.com/docs/resources/tos-privacy/ │ │ │ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` Then set the GOOGLE\_CLOUD\_PROJECT to a valid project setup on the Google Cloud console: ```shell ~ $ export GOOGLE_CLOUD_PROJECT=comglitn ~ $ ``` Other options include Google Cloud API Key that can be generated directly from the Google Cloud Console. #### Installing Google Cloud Tools To simplify working with Google Cloud — install the Google Cloud Tools: ```plaintext https://docs.cloud.google.com/sdk/docs/install-sdk ``` Once the installation is completed — you can verify the setup: ```shell william@Azure:~$ gcloud auth list Credentialed Accounts ACTIVE ACCOUNT * [email protected] ``` #### Installing Azure Customized GEMINI.md A sample GitHub repo contains tools for working with Gemini CLI on Azure. This repo is available here: ```shell git clone https://gitHub.com/xbill9/gemini-cli-azure ``` A sample **GEMINI.md** customized for the Azure environment is provided in the repo: ```markdown This is a multi linux git repo hosted at: github.com/xbill9/gemini-cli-azure You are a cross platform developer working with Microsoft Azure and Google Cloud You can use the Azure CLI : https://learn.microsoft.com/en-us/cli/azure/install-azure-cli https://learn.microsoft.com/en-us/cli/azure/ https://learn.microsoft.com/en-us/cli/azure/reference https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux?view=azure-cli-latest&pivots=apt ## Azure CLI Tools You can use the Azure CLI to manage resources across Azure Storage, Virtual Machines, and other services. - **List Resource Groups** : `az group list -o table` - **List Storage Accounts** : `az storage account list -o table` - **List Virtual Machines** : `az vm list -d -o table` ### Azure Update Script - `azure-update`: This script is specifically for Azure Linux environments. It updates all packages and ensures necessary libraries are installed. ## Automation Scripts This repository contains scripts for updating various Linux environments and tools: - `linux-update`: Detects OS (Debian/Ubuntu/Azure Linux) and runs the corresponding update scripts. - `azure-update`: Updates Azure Linux packages and installs necessary dependencies. - `debian-update`: Updates Debian/Ubuntu packages and installs `git`. - `gemini-update`: Updates the `@google/gemini-cli` via npm and checks versions of Node.js and Gemini. - `nvm-update`: Installs NVM (Node Version Manager) and Node.js version 25. ``` #### Python MCP Documentation The official GitHub Repo provides samples and documentation for getting started: [GitHub - modelcontextprotocol/python-sdk: The official Python SDK for Model Context Protocol servers and clients](https://github.com/modelcontextprotocol/python-sdk) The most common MCP Python deployment path uses the FASTMCP library: [Welcome to FastMCP - FastMCP](https://gofastmcp.com/getting-started/welcome) #### 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 Python MCP Server was built with stdio transport. This server was validated with Gemini CLI in the local environment. This current setup validates the connection from Gemini CLI to the local process via MCP. The MCP client (Gemini CLI) and the Python MCP server both run in the same local environment. Next- the basic MCP server is extended with Gemini CLI to add several new tools in standard Python code. #### Setup the Basic Environment At this point you should have a working Python interpreter and a working Gemini CLI installation. The next step is to clone the GitHub samples repository with support scripts: ```shell cd ~ git clone https://github.com/xbill9/gemini-cli-azure ``` Then run **init.sh** from the cloned directory. The script will attempt to determine your shell environment and set the correct variables: ```shell cd gemini-cli-azure 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: ```shell cd gemini-cli-azure 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 be in the same environment or distributed over the Internet. The connection over HTTP will look similar to this: ```python mcp.run( transport="http", host="0.0.0.0", port=port, ) ``` #### Running the Python Code First- switch the directory with the Python MCP sample code: ```shell CD mcp-aks-python-azure make install make run ``` You can validate the final result by checking the messages: ```plaintext [04/02/26 16:02:19] INFO Starting MCP server 'hello-world-server' with transport 'http' on transport.py:299 http://0.0.0.0:8080/mcp INFO: Started server process [16625] INFO: Waiting for application startup. {"message": "StreamableHTTP session manager started"} INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) ``` Once you have validated the server can run locally — exit with control-c. Then run a deployment to Azure Kubernates Service: ```plaintext > make deploy ✦ I'll check if the AKS cluster exists before proceeding with the deployment. ✦ The make deploy command was successful. The Python-based MCP server is now running on Azure Kubernetes Service (AKS). Deployment Details: - ACR Image: mcpacrpenguinv2.azurecr.io/mcp-server-image:921e6f8 - AKS Cluster: mcp-aks-penguin - AKS Service IP: 20.99.165.219 - Pod Status: Running (1/1 READY) You can now access the MCP server at http://20.99.165.219. ``` Getting deployment status: ```plaintext ✦ The current status of your Azure resources is as follows: - AKS Cluster (mcp-aks-penguin): Succeeded, version 1.34. - Kubernetes Service (mcp-server-service): LoadBalancer type, with External IP 20.99.165.219. - Kubernetes Pods: The mcp-server pod is Running and healthy (1/1 READY). ``` And the current endpoint: ```plaintext │ │AKS Endpoint: │ │ 20.99.165.219 ``` #### Gemini CLI settings.json The default Gemini CLI settings.json has an entry for the Python source: ```json 1 { 2 "mcpServers": { 3 "azure-aks-python": { 4 "httpUrl": "http://20.99.165.219/mcp" 5 } 6 } 7 } ``` #### Validation with Gemini CLI Leaver the MCP server window running. Start a new shell. Gemini CLI is restarted and the MCP connection over HTTP to the Python Code is validated, The full Gemini CLI Session will start: ```plaintext ▝▜▄ Gemini CLI v0.34.0 ▝▜▄ ▗▟▀ Signed in with Google: [email protected] /auth ▝▀ Plan: Gemini Code Assist Standard /upgrade > /mcp list Configured MCP servers: 🟢 azure-aks-python - Ready (1 tool) Tools: - mcp_azure-aks-python_greet 🟢 DeveloperKnowledge (from DeveloperKnowledge) - Ready (2 tools) Tools: - mcp_DeveloperKnowledge_get_documents - mcp_DeveloperKnowledge_search_documents ``` And you can then connect to the MCP Server over HTTP: ```plaintext > greet AKS! ✦ I will now greet AKS! by calling the mcp_azure-aks-python_greet tool. ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ greet (azure-aks-python MCP Server) {"param":"AKS!"} │ │ │ │ AKS! │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ AKS! ``` #### Project Review Finally — you can use Gemini CLI to review the project: ```plaintext ✦ I have conducted a comprehensive code review of the project. Overall, the implementation is clean, follows cloud-native best practices, and is well-configured for AKS. Here are my specific findings and recommendations: 1. Architecture & Implementation (main.py) - FastMCP: Excellent use of the FastMCP library, which simplifies server creation and tool definition. - Health Check: The /health custom route is correctly implemented and integrated with Kubernetes liveness and readiness probes. - Logging: Using python-json-logger for JSON-formatted logs is a best practice for containerized environments, facilitating better observability in Azure. - Tooling: The greet tool is functional and correctly typed. 2. Containerization (Dockerfile) - Optimization: The use of python:3.13-slim and proper layer ordering (copying requirements.txt before code) ensures small image sizes and fast rebuilds. - Environment: PYTHONUNBUFFERED=1 is correctly set to ensure logs are emitted immediately. 3. Orchestration (k8s.yaml) - Probes: Well-defined liveness and readiness probes ensure high availability. - Resources: CPU and memory limits/requests are specified, which prevents resource exhaustion in the cluster. - Security: The securityContext dropping all capabilities is a strong security measure. - Improvement: Consider adding runAsNonRoot: true and allowPrivilegeEscalation: false to further harden the deployment. 4. Automation (Makefile) - AKS Focus: The recent cleanup has effectively focused the automation on the AKS workflow. - ACR Integration: The aks-create target correctly uses --attach-acr, simplifying permission management between AKS and the registry. - Cleanup: The new destroy target provides a simple way to tear down all resources. - Note: The AZ_ACR_NAME uses a dynamic hostname-based suffix, which is a clever way to avoid global naming collisions in Azure. 5. Dependencies (requirements.txt) - Recommendation: Currently, dependencies are not version-pinned. For consistent deployments, it's recommended to pin versions (e.g., fastmcp==0.4.1). 6. Project Documentation (GEMINI.md & README.md) - Consistency: Both files are now aligned with the AKS-only deployment strategy. --- Final Verdict: The project is in excellent shape for an AKS-based MCP server. The transition from ACA to AKS is complete and well-documented. ``` #### Summary The strategy for using Python for MCP development with Gemini CLI was validated with a incremental step by step approach. A minimal HTTP transport MCP Server was started from Python source code and validated with Gemini CLI running as a MCP client in the same local environment. Then this solution was deployed remotely to the Azure Kubernates Service and validated with the local installation of Gemini CLI. This approach can be extended to more complex deployments using other MCP transports and Cloud based options.