# USPS Developer Portal MCP > USPS Developer Portal connects your AI agent directly to official United States Postal Service data. Verify addresses, calculate accurate shipping rates for domestic or international routes, audit package tracking history, and look up ZIP code metadata—all without leaving your chat client. ## Overview - **Category:** industry-titans - **Price:** Free - **Tags:** address-verification, package-tracking, zip-codes, postal-services, logistics ## Description Your agent connects you straight to official USPS data. You don't need to juggle a bunch of websites—your client handles all the postal logistics in one conversation. **Verify US Addresses & Map Locations:** When you get an address from a customer, you gotta make sure it's legit and standardized first. Use `verify_usps_address` to validate any full U.S. street address against official USPS records; this guarantees your fulfillment metadata is spot-on. If you only have a ZIP code but need the city or state, run that through `lookup_usps_city_state`. Need the proper ZIP code for a given street address? You'll use `lookup_usps_zip_code` to nail down the most accurate five digits. **Determine Shipping Costs & Timelines:** Figuring out shipping costs is simple. For stuff staying within the U.S., you call `calculate_domestic_rate` and it spits out the exact cost based on weight and destination mail classes. If you're sending packages across borders, use `calculate_international_rate` to get those overseas rates. You also need to know when it's gonna arrive. Run a query using `get_delivery_commitments`, and your agent pulls live delivery commitments, giving you estimated arrival dates based on the service level you pick. **Track Packages & Audit History:** Checking where that package is? It's easy. You give your tracking number to `track_usps_package`, and it tells you the current status right now. But if you need the full story—like a proper audit trail for complex shipments—you use `track_usps_package_advanced`. This tool pulls detailed, facility-level event history, showing every single step the package took from origin to destination. This setup means your agent handles everything: standardizing an address with `verify_usps_address`, finding the ZIP for a street using `lookup_usps_zip_code`, cross-referencing that ZIP code back to the city and state via `lookup_usps_city_state`. When it comes to rates, you'll use `calculate_domestic_rate` for U.S.-only shipments or `calculate_international_rate` if you're sending stuff overseas. You can also get a timeline estimate with `get_delivery_commitments`, which provides those service-level dates. For tracking, start by checking the status quickly with `track_usps_package`. But remember that for deep dives—for seeing every single facility scan and transfer event—you gotta use `track_usps_package_advanced`. It gives you the granular view of the shipment's entire journey. You don't have to open a browser or switch tabs; your agent just does it all in plain conversation. ## Tools ### calculate_domestic_rate Calculates the shipping cost for packages traveling within US domestic routes. ### calculate_international_rate Determines the shipping cost for packages crossing international borders. ### get_delivery_commitments Retrieves estimated delivery dates and service level commitments from USPS. ### lookup_usps_city_state Maps a known ZIP code back to its corresponding city and state pair. ### lookup_usps_zip_code Finds the most accurate ZIP code for a given US street address. ### track_usps_package Checks the current status of a package using its main tracking number. ### track_usps_package_advanced Retrieves detailed, facility-level event history for complex shipment auditing. ### verify_usps_address Standardizes and validates a full US address against USPS official records. ## Prompt Examples **Prompt:** ``` Verify address '1600 Pennsylvania Avenue NW, Washington, DC 20500' using USPS. ``` **Response:** ``` I've retrieved the verification metadata from USPS! The address is identified as valid and standardized. Would you like the full XML response or the ZIP+4 metadata for this location? ``` **Prompt:** ``` Track my package with tracking number '9400100000000000000000'. ``` **Response:** ``` I've checked the status for that tracking number. It is currently identified as 'Delivered' at [Time]. I can assist you with the full event history metadata for this shipment if you'd like. ``` **Prompt:** ``` Lookup ZIP code for 'Seattle, WA'. ``` **Response:** ``` I've retrieved the ZIP code metadata for Seattle! Notable codes include 98101 and 98104. I can provide the specific address-level ZIP details to assist in your regional logistics audit. ``` ## Capabilities ### Validate US Addresses Standardizes and verifies any United States street address using official USPS web tools. ### Get Shipment Tracking Details Retrieves the current status and detailed event history for a package using its tracking number. ### Calculate Shipping Costs Determines the real-time cost of shipping across various mail classes, weights, and global destinations. ### Map ZIP Codes to Locations Looks up the specific city and state associated with any given US ZIP code. ### Determine Delivery Timelines Queries live delivery commitments, providing estimated arrival dates based on mail class and service level. ## Use Cases ### Preparing for a Bulk Shipment Audit The Operations Lead has 50 addresses from a new client, but they're messy. They run the list through the agent: 'Run `verify_usps_address` on these 50 locations.' The agent returns a clean CSV of standardized data, ready for label generation. ### Debugging Delayed Deliveries A client claims their package is late. Instead of just checking the status via `track_usps_package`, they run the advanced tool: 'Check full history for tracking number X.' The agent pulls detailed records showing exactly which facility stalled the shipment. ### Calculating Dynamic Pricing An e-commerce bot needs to show shipping costs in real time. It calls `calculate_domestic_rate` with the package dimensions and destination ZIP, getting an instant, accurate price that changes if the weight shifts. ### Cross-Referencing Location Data A data researcher needs to verify a region's postal structure. They prompt: 'What is the city and state for 98104?' The agent uses `lookup_usps_city_state` to confirm the location, adding precision to their database. ## Benefits - Accuracy: Don't guess on addresses. Use `verify_usps_address` to ensure every US location is standardized against official USPS records, preventing costly label errors. - Cost Control: Stop calculating shipping costs manually. Call `calculate_domestic_rate` or `calculate_international_rate` to get instant, accurate pricing based on weight and destination. - Deep Visibility: When a package gets stuck, don't rely on the surface status. Use `track_usps_package_advanced` to pull granular, facility-level event data for full transparency. - Geo-Mapping: Need to know what area a code belongs to? Use `lookup_usps_zip_code` and `lookup_usps_city_state` to map out regional logistics boundaries instantly. - Timing Guarantees: Before promising delivery, check the service level. `get_delivery_commitments` provides live estimates based on USPS mail classes. ## How It Works The bottom line is: you talk to your AI client, and it handles all the required API calls to get a single, verified answer. 1. Subscribe to the server and provide your USPS Web Tools User ID. 2. Ask your AI client a direct question (e.g., 'What is the cost to ship 5 lbs from NY to CA?'). 3. The agent executes the necessary tool calls, gathers data, and returns a summarized, actionable answer. ## Frequently Asked Questions **How do I use `verify_usps_address` with this server?** You pass the full address string directly to your agent. The tool validates and standardizes it against official USPS records, confirming if the format is correct and usable for shipping. **`calculate_domestic_rate` or `calculate_international_rate`? Which one do I use?** Use `calculate_domestic_rate` only when both the origin and destination are within the United States. Use `calculate_international_rate` for anything crossing US borders. **What's the difference between `track_usps_package` and `track_usps_package_advanced`?** `track_usps_package` gives you the current, top-line status. The advanced tool provides a deep dive into the full event history—every scan location, date, and time—which is better for auditing. **Can I use `lookup_usps_zip_code` if I only have a general address?** Yes. It takes a specific US street address and runs it through the system to find the most accurate, detailed ZIP code for that location. **How do I authenticate to run `verify_usps_address`?** You must provide your USPS Web Tools User ID in the server setup. The agent uses this unique ID to authorize all calls, ensuring you are billed correctly and accessing the official data endpoints. **If I run `lookup_usps_zip_code` for an invalid address, what happens?** The system returns a structured error code instead of failing. This prevents bad data from entering your workflow, allowing your agent to catch the failure and prompt you for correction. **Can I batch run `lookup_usps_city_state` for multiple ZIP codes?** Yes, you can pass an array of ZIP codes as input. This handles bulk lookups efficiently, saving time when auditing large regional datasets. **When I call `get_delivery_commitments`, what format is the delivery estimate metadata in?** The results arrive in clean JSON format. This structure makes it easy for your agent to parse and use the specific commitment dates or estimated service times. **How do I find my USPS User ID?** Register for an account at the [**USPS Web Tools registration page**](https://www.usps.com/business/web-tools-apis/welcome.htm). You will receive your User ID via email. Copy and paste it below. **Does it support international tracking?** Yes. The `track_usps_package` tool supports tracking for any valid USPS tracking number, including international shipments originating from or delivered by USPS. **What is the format for address verification?** The API requires an object with line1, city, and state metadata. Standardizing these inputs ensures the most accurate verification from the USPS database.