ryan-l-talbert-usps/addresses-mcp-server-uspscio

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

{
	"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

{
	"IsEncrypted": false,
	"Values": {
		"FUNCTIONS_WORKER_RUNTIME": "python",
		"AzureWebJobsStorage": "UseDevelopmentStorage=true"
	}
}

3. Run Azure Storage Locally (Azurite with Podman)

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):

uv init
uv venv
source .venv/bin/activate
uv add azure-functions requests

5. MCP Inspector

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:

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):

@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

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):

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

5. 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:

{
	"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

5. 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

5. 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.