Every MCP tool call runs as you — rate lookups, label purchases, and billing are scoped to your account exactly as if you'd used the app directly. There are two ways to connect:
An API key is sent as a standard bearer token:
Authorization: Bearer bnb_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxAPI keys can be revoked at any time from the same settings screen — a revoked key is rejected immediately.
https://yourdomain.com/mcptext/event-stream body rather than plain JSON. The endpoint works with or without a trailing slash (/mcp and /mcp/).
claude mcp add --transport http boxnearby https://yourdomain.com/mcp \
--header "Authorization: Bearer YOUR_API_KEY"Or directly in .mcp.json / ~/.claude.json:
{
"mcpServers": {
"boxnearby": {
"type": "http",
"url": "https://yourdomain.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Add a custom connector (Settings → Connectors) with the URL https://yourdomain.com/mcp. Leave any OAuth client ID or secret fields blank. You'll be sent to BoxNearby to sign in and click Allow, then returned to claude.ai.
Any client that lets you configure a remote HTTP MCP server with a custom header uses the same url + headers shape — Claude Desktop's config file, for example. Clients that support OAuth for remote servers can connect with just the URL.
get_shipping_ratesGet USPS/UPS home-delivery rate quotes for a package. Call this first to choose a carrier/service pair for create_shipping_label.
| Parameter | Type | Notes |
|---|---|---|
| sender_name, sender_street1, sender_city, sender_state, sender_zip | string | |
| recipient_name, recipient_street1, recipient_city, recipient_state, recipient_zip | string | |
| weight_lb, length_in, width_in, height_in | number |
Returns:
{
"rates": [
{ "carrier": "UPS", "service": "UPSGroundsaverGreaterThan1lb", "price_usd": 11.14, "delivery_days": "5 business days" },
{ "carrier": "USPS (EP)", "service": "GroundAdvantage", "price_usd": 11.69, "delivery_days": "3 business days" }
]
}Rates aren't cached — create_shipping_label re-fetches fresh rates itself, so quotes here are indicative, not locked in.
find_pickup_hubsFind nearby USPS Post Offices and Smart Lockers.
| Parameter | Type | Notes |
|---|---|---|
| location | string | Free-form address or place name, e.g. "94103" or "123 Main St, San Francisco, CA" |
| radius_miles | integer | Default 5 |
Returns {"hubs": [{"id", "name", "type", "address", "distance_miles"}, ...]}.
create_shipping_labelStart purchasing a home-delivery label for a carrier/service pair from get_shipping_rates.
Takes the same sender/recipient/parcel fields as get_shipping_rates, plus carrier and service (must match an option currently available for this exact shipment).
By default, a person pays. Stripe Checkout needs a human to open a URL and enter card details, so the tool returns a checkout link and an order id instead:
{
"order_id": "205db6a1-cc6c-41ed-a0da-cee4d0d78d32",
"checkout_url": "https://checkout.stripe.com/c/pay/cs_test_...",
"amount_usd": 11.14,
"carrier": "UPS",
"service": "UPSGroundsaverGreaterThan1lb"
}Surface checkout_url to the user, then poll get_label_status once they've paid. If the carrier/service pairing no longer matches an available rate, this returns an error asking you to call get_shipping_rates again.
Optionally, charge your membership card. You can turn on Settings → Profile → AI Agent Purchases to let your agent buy labels without a checkout page. It's off by default and uses the card you already pay your membership plan with — there's nothing separate to add (a membership paid from a bank account can't be charged instantly, so switch it to a card first). You set both a maximum per label and a maximum per 24 hours. When a label fits, your card is charged right away and the call returns the finished label ("paid_automatically": true, with label_url and tracking_number). Anything over a limit, or a declined card, simply falls back to the checkout link above, with an auto_pay field explaining why. Every automatic purchase is emailed to you and appears in My Messages, and if the label can't be created you're refunded automatically.
get_label_statusPoll a purchase started with create_shipping_label, given its order_id.
{ "status": "pending", "label_url": null, "tracking_number": null, "error": null }status progresses pending (awaiting payment) → processing → complete (with label_url/tracking_number) or error (refunded automatically).
find_pickup_hubs is lookup-only.