This project includes two sides: a Python MCP server and a Python MCP client, both built using the Starlette framework and the MCP Streamable HTTP transport protocol. The MCP server also includes additional non-MCP routes for standard web functionality.

This project is a template for developing applications that use the Model Context Protocol (MCP) as a way to coordinate across clients and servers. The guide below will help you get started with the project, deploy it to Azure, and/or run it locally.

• Features
• Getting started
  • GitHub Codespaces
  • VS Code Dev Containers
  • Local Environment
• Deploying
• Development server

• Streamable HTTP transport protocol for MCP
• Starlette framework integration with custom routes
• Unified web application with both MCP and standard web endpoints
• Clean separation of concerns between MCP and web functionality
• Simple MCP client that can be used to test the MCP server endpoints

You have a few options for getting started with this template. The quickest way to get started is GitHub Codespaces, since it will setup all the tools for you, but you can also set it up locally.

You can run this template virtually by using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:

1. Open the template (this may take several minutes):

   

2. Open a terminal window

3. Continue with the deploying steps

A related option is VS Code Dev Containers, which will open the project in your local VS Code using the Dev Containers extension:

1. Start Docker Desktop (install it if not already installed)

2. Open the project:

   

3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.

4. Continue with the deploying steps

If you're not using one of the above options for opening the project, then you'll need to:

1. Make sure the following tools are installed:

   • Docker Desktop
   • Azure CLI
   • Python 3.13
   • UV Package Manager

2. Clone this repository:

   git clone https://github.com/pamelafox/python-mcp-starlette-client-server.git

3. Open the project folder

4. Create a Python virtual environment and activate it.

   uv venv

5. Install the the MCP server packages:

   uv pip install -e mcp_server

6. Install the MCP client packages:

   uv pip install -e mcp_client

7. Continue with the deploying steps.

1. Login to Azure:

   az login

2. Install the container apps extension if you haven't already:

   az extension add --name containerapp --upgrade

3. Store the following values in variables:

   export RESOURCEGROUP="your-resource-group-name"
   export LOCATION="your-azure-region" # e.g., eastus, westus, etc.
   export CONTAINERAPPSENV="your-container-apps-environment-name"

   Replace your-resource-group-name, your-azure-region, and your-container-apps-environment-name with your desired values.

4. Create a resource group:

   az group create --name $RESOURCEGROUP --location $LOCATION

5. Create an Azure Container Apps environment:

   az containerapp env create --name $CONTAINERAPPSENV --resource-group $RESOURCEGROUP --location $LOCATION

6. Run this command to deploy the application to Azure Container Apps:

   az containerapp compose create --compose-file-path docker-compose.yaml -g $RESOURCEGROUP --environment $CONTAINERAPPSENV

7. Save the URL of the deployed server application:

   DEPLOYED_SERVER_HOST=$(az containerapp show --name mcpserver --query properties.configuration.ingress.fqdn --resource-group $RESOURCEGROUP -o tsv)

8. Update the SERVER_URL environment variable of the client application to point to the deployed server URL:

   az containerapp update --name mcpclient --resource-group $RESOURCEGROUP --set-env-vars SERVER_URL="https://$DEPLOYED_SERVER_HOST/mcp/"

9. Navigate to the mcpclient app in the Azure Portal and view the logs to see the client connecting to the server.

To run the MCP server and client in your local development environment, the easiest way is to use the provided Docker Compose file. This will set up both the MCP server and client in containers, and show the output in your terminal.

docker compose up

You can also run them each separately if you prefer, or run them without Docker, as described below.

Assuming you've run the steps to open the project, you can now run the app in your development environment:

To run the MCP server with Docker:

docker build -t mcp-server mcp-server
docker run -p 8000:8000 mcp-server

To run the MCP server without Docker:

cd mcp-server
uv run mcp-server

To use the MCP Dev Inspector to test the server:

uv run mcp dev mcp-server/src/mcp_server/weather.py

To run the MCP client with Docker:

docker build -t mcp-client mcp-client
docker run -e SERVER_URL=http://localhost:8000/mcp/ mcp-client

To run the MCP client without Docker:

cd mcp-client
uv run mcp-client