Content
USPS Addresses MCP Server (Azure Functions)
===========================================
This repository hosts an Azure Functions–based Model Context Protocol (MCP) server that exposes USPS **Addresses** tools (city/state lookup by ZIP, address standardization, ZIP/ZIP+4 lookup). It mirrors the structure of the earlier "domestic pricing" example, but all references have been updated to the USPS Addresses APIs. You can run it locally for development and then deploy to Azure Functions (Linux, Flex Consumption).
Two deployment workflows are documented below:
1. Manual (Azure Portal + CLI) end‑to‑end steps.
2. VS Code Azure extension workflow.
---
Deploying the Addresses MCP Server on Azure Functions
=====================================================
1. Set Up Azure Function in Azure Portal
----------------------------------------
* Plan type: **Flex Consumption** (~512MB memory)
* Add **Azure Storage** (create an empty Blob container)
* (Optional) **Application Insights**
* Configuration → Application settings (environment variables):
* `FUNCTIONS_WORKER_RUNTIME=python`
* `AzureWebJobsStorage=UseDevelopmentStorage=true` (or real storage connection string)
* Confirm OS is **Linux** on the Overview page
* Note default domain: `<your-app>.azurewebsites.net`
2. Project Structure
--------------------
```
/├── .venv/
├── .gitignore
├── host.json
├── local.settings.json
├── requirements.txt
├── function_app.py
├── .funcignore
└── README.md
```
Key files:
* `requirements.txt`
* `host.json`
* `local.settings.json`
* `function_app.py`
* `.funcignore`
### Example: host.json
```json
{
"version": "2.0",
"logging": {
"applicationInsights": {
"samplingSettings": {
"isEnabled": true,
"excludedTypes": "Request"
}
},
"logLevel": { "default": "Debug" }
},
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle.Experimental",
"version": "[4.* , 5.0.0)"
}
}
```
### Example: local.settings.json
```json
{
"IsEncrypted": false,
"Values": {
"FUNCTIONS_WORKER_RUNTIME": "python",
"AzureWebJobsStorage": "UseDevelopmentStorage=true"
}
}
```
3. Run Azure Storage Locally (Azurite with Podman)
--------------------------------------------------
```bash
podman machine start
podman run -d --name azurite \
-p 10000:10000 -p 10001:10001 -p 10002:10002 \
mcr.microsoft.com/azure-storage/azurite
podman ps -a
```
4. Python Environment Setup
---------------------------
You can use `uv` (or plain venv / pip):
```bash
uv init
uv venv
source .venv/bin/activate
uv add azure-functions requests
```
5. MCP Inspector
----------------
```bash
npm install -g npx
npx @modelcontextprotocol/inspector
```
Inspector URL: http://127.0.0.1:6274
6. Address MCP Tools (`function_app.py`)
---------------------------------------
The app defines three MCP tools exposed via generic triggers:
| Tool Name | Purpose | Key Required Args |
|-----------|---------|-------------------|
| `get_city_state_by_zip` | Lookup primary city & state for a 5‑digit ZIP | `access_token`, `zip_code` |
| `standardize_address` | Standardize a postal address | `access_token`, `street_address`, `state` |
| `get_zip_code` | Retrieve ZIP / ZIP+4 for an address | `access_token`, `street_address`, `city`, `state` |
Each tool expects a JSON arguments object; optional fields (firm, secondary unit designator, etc.) are included where supported.
Abbreviated example snippet (see full file for details):
```python
@app.generic_trigger(
arg_name="context",
type="mcpToolTrigger",
toolName="get_city_state_by_zip",
description="Get city and state information for a given 5-digit ZIP code.",
toolProperties=tool_properties_get_city_state_by_zip,
)
def get_city_state_by_zip(context):
# Parses context JSON, calls USPS Addresses API city-state endpoint
...
```
7. Run Function Locally
-----------------------
```bash
source .venv/bin/activate
func start
```
Local MCP SSE endpoint:
```
http://localhost:7071/runtime/webhooks/mcp/sse
```
Use MCP Inspector with that URL, then invoke one of the tools (provide arguments JSON matching required properties).
8. Deploy to Azure Function
---------------------------
Package & deploy (example):
```bash
zip -r addressesFunc.zip . \
-x "./.venv/*" -x "*.git*" -x ./.vscode -x .env \
-x "*__pycache__/*" -x "*/__pycache__/*"
az login
az functionapp deployment source config-zip \
--src addressesFunc.zip \
--name <your-function-app> \
--resource-group <your-resource-group> \
--build-remote true
```
9. Test Cloud MCP Server
------------------------
* In Azure Portal → **Functions > App keys** → copy the `mcp_extension` key.
* Construct URL:
```
https://<your-function-app>.azurewebsites.net/runtime/webhooks/mcp/sse?code=<mcp_extension_key>
```
* Paste into MCP Inspector → run e.g. `get_city_state_by_zip`.
✅ Your USPS Addresses MCP server now runs locally and in the cloud.
---
Deploying with Azure VS Code Extension
======================================
1. Prerequisites
----------------
* (If needed) Configure corporate proxy in VS Code
* Install Azure Tools / Azure Functions extension
2. Create Function App in Azure
-------------------------------
1. In VS Code Azure panel, select your resource group
2. Right‑click **Function App** → **Create Function App in Azure**
3. Follow prompts (name, region, Python runtime, secrets management)
4. Wait for successful creation
3. Create Local Function Project
--------------------------------
1. In VS Code → **Create Function Project…**
2. Choose Python, interpreter, (you can skip adding a trigger initially)
3. Replace / edit `function_app.py` with the tools from this repo
4. Update host.json (Preview Bundle)
-----------------------------------
If needed, switch to the Preview bundle to ensure MCP extension availability:
```json
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
"version": "[4.* , 5.0.0)"
}
}
```
This generates the `mcp_extension` key required for MCP webhook access.
5. Deploy from VS Code
----------------------
1. Right‑click the local project folder in the Azure extension panel
2. Select **Deploy to Function App…**
3. Choose Subscription → existing Function App
4. Confirm deployment
6. Retrieve MCP Extension Key
-----------------------------
1. Open Azure Portal
2. Navigate to your Function App
3. Go to **Functions > App keys**
4. Copy the `mcp_extension` key
7. Access Your Cloud MCP Server
-------------------------------
```
https://<your-function-app>.azurewebsites.net/runtime/webhooks/mcp/sse?code=<mcp_extension_key>
```
Invoke tools via MCP Inspector or any MCP-compatible client.
✅ Deployment complete – your USPS Addresses MCP tools are live.
---
Troubleshooting Tips
--------------------
* 401 / 403 calling USPS API: ensure valid OAuth `access_token` passed to tool.
* Empty results: verify address components; try removing optional fields.
* Slow cold start: Flex Consumption may cold start; add simple ping/keep-warm if needed.
* Missing `mcp_extension` key: confirm Preview or Experimental extension bundle in `host.json` and restart.
Next Ideas
----------
* Add caching (e.g. Azure Cache for Redis) for repeated ZIP lookups.
* Implement batch address standardization tool.
* Add unit tests for argument validation.
License
-------
Internal / Example – adapt as needed.
