Apigee-Authorization-Air-Quality-MCP by DinoChiesa - MCP Server

Governed MCP Example - Air Quality Server

I built this to illustrate governance that I can apply on any MCP Server that can be accessed over HTTP, through Apigee.

This repo contains:

an example MCP Server implemented in python, using the FastMCP framework from jlowin. The server provides air quality sensor readings for places. The server does not perform any authorization check.
an example Apigee API Proxy, that acts as a facade for that Server, providing the authorization check and a 401 WWW-Authenticate interception.

Disclaimer

This example is not an official Google product, nor is it part of an official Google product.

Screencast

This Screencast walks through the process.

Using it

You can do it yourself.

To set this up, you need a GCP project suitable for Cloud Run, and an Apigee instance. You need the proper roles and permissions:

to create service accounts,
deploy services to Cloud Run,
create and manage secrets in Secret Manager
and import + deploy Apigee proxies.

The setup scripts use things like apigeecli, and gcloud.

Prerequisites

You will need to obtain credentials (API Keys) for the TomTom and Open Air Quality services by visiting:
- https://developer.tomtom.com/
- https://docs.openaq.org/
You need to set up an OpenID Connect IDP, and provision a new Client ID and Secret pair. Steps for this varies, depending on your IDP. For setting up Auth0, you can try .

This example will work with any OIDC-compliant IDP, but I don't have the specific steps for each IDP.
If you want to use Gemini CLI as your MCP client, you also need an API Key for Gemini. Get one at https://ai.studio

You can alternatively use VSCode as your MCP Client, or MCP Inspector, or some other client. I don't have instructions for using those options.

Service and Proxy Provisioning Steps

With a text editor, open the file, and modify it to use your settings.

About these settings:

setting	description
`CLOUDRUN_PROJECT_ID`	The ID of a GCP project, that will run the example MCP Server.
`CLOUDRUN_REGION`	The region (eg `us-west1`) to use for the Cloud Run service
`APIGEE_PROJECT_ID`	The GCP project hosting Apigee. This can be the same as the Cloud Run project, but need not be.
`APIGEE_ENV`	the Apigee environment.
`APIGEE_HOST`	DNS hostname defined in Apigee that will allow invocation of the proxy
`OIDC_SERVER`	# The base for your OIDC server. See comments below.
`TOMTOM_API_KEY`	An API key for TomTom that you can get for free from https://developer.tomtom.com/
`OPENAQ_API_KEY`	An API Key for Open AQ that you can get for free from https://docs.openaq.org/
`CLOUDRUN_SERVICE_NAME`	Name of the Cloud Run service.
`CLOUDRUN_SHORT_SA`	Name of the service account used by the Cloud Run service.

Related to the OIDC Server: This example uses OAuth2 and authorization code grant. It requires an OpenID Connect IDentity provider, something like Auth0 or Entra ID or ForgeRock and so on. For an Auth0 tenant, the value will be something like https://dev-RANDOM-CHARS-HERE.us.auth0.com/ .

Whatever you use, it should comply with IETF RFC 8414; an MCP client will call

  GET ${OIDC_SERVER}/.well-known/oauth-authorization-server

...to discover the authorize and token endpoints. These are usually /authorize and /token , but not always.

After getting all these settings save the modifications to a file, perhaps named .env.

Open a terminal window. Source the modified file you just saved, to get all of those settings into your environment.
```
source .env
```
Create the service account for the Cloud Run service.
```
./1-create-service-account-for-mcp-server.sh
```
Provision the secrets into Secret Manager. These include the TomTom and OpenAQ keys.
```
./2-provision-secrets.sh
```
Deploy the MCP Server to Cloud Run
```
./3-deploy-mcp-to-cloud-run.sh
```
You should now be able to interact with the MCP Server at the endpoint emitted by the deployment script.
- You can use the MCP Inspector to do this.
- Or, to use Gemini CLI, open or create the file ~/.gemini/settings.json and provide this configuration:
```
{
  "mcpServers": {
    "air-quality": {
      "httpUrl": "https://air-quality-1923-999999222.us-west1.run.app/mcp"
    }
  }
  ....
}
```
  Replace the URL with the one from your Cloud Run service. Then, start Gemini CLI and you should be able to interact with the MCP Server.
- You can also use VSCode as the MCP Client. In that case, use this for your MCP configuration:
```
{
  "servers": {
    "air-quality": {
      "url": "https://air-quality-1923-999999222.us-west1.run.app/mcp"
      "type": "http"
    }
  },

  "inputs": []
}
```
If you do not already have it, install the apigeecli
```
./8-install-apigeecli.sh
```
Import and deploy the Apigee proxy:
```
./9-import-and-deploy-apigee-proxy.sh
```
At this point, if you configure the Apigee proxy as the MCP endpoint and use your MCP client (Gemini CLI, VSCode, MCP Inspector, and so on), you should see the OpenID Connect signin at the appropriate time.
- To do this with Gemini CLI, modify the ~/.gemini/settings.json file to provide this configuration:
```
{
  "mcpServers": {
    "air-quality-oauth": {
      "httpUrl": "https://apigee.endpoint.for.you/air-quality-oauth/mcp",
      "timeout": 4400,
      "oauth": {
        "enabled": true,
        "clientId": "OPENID_CLIENT_ID",
        "clientSecret": "OPENID_CLIENT_SECRET",
        "audiences": ["air-quality-oauth"]
      }
    }
  }
  ....
}
```
  Replace the URL with the one from your Apigee proxy, and use the appropriate CLIENT ID and Secret from your OpenID IDP. Then, re-start Gemini CLI and type /mcp auth air-quality-oauth, and you'll see the signin, and afterwards you will be able to interact with the service.
- If you are using VSCode as the MCP client, stop and restart VSCode, and when you start the MCP server, you will see the signin experience. For VScode you do not need to modify the mcp.json file, but you will need to interactively supply the client ID and Secret at runtime.

Discussion

This is just an example. It illustrates the basics. Probably you will want to extend this idea for your purposes. Here are some ideas:

Multiple MCPs. While this example shows a single API Proxy acting as a facade for a single MCP Server, in the general case companies will have lots of MCP servers. Using wildcard basepaths and a simple lookup table, it's trivial to use a single API Proxy as a facade for a large number of MCP Servers.
API Product check. By including a VerifyAPIKey policy into the API Proxy, you can also check the entitlement of the client for a particular API Product.
User-based Authorization check. By including a ServiceCallout to a policy decision point (Something like OPA), you could include fine-grained dynamic authorization check in the Apigee proxy.

License

This material is . and is licensed under the .

Support

This example is open-source software. If you need assistance, you can try inquiring on the Google Cloud Community forum dedicated to Apigee There is no service-level guarantee for responses to inquiries posted to that site.