How do I install the Upgrade Shippo skill?

Run npx skillmds@latest add goshippo/upgrade-shippo in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Upgrade Shippo safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Upgrade Shippo?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Upgrade Shippo free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Upgrade Shippo?

goshippo (@goshippo) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Upgrade Shippo by goshippo — Agent Skill

Name: Upgrade Shippo
Author: goshippo

Upgrade Shippo

Guide for Shippo API version changes, webhook payload versioning, and how the hosted MCP server handles updates. Use when reasoning about backward compatibility, handling new fields in webhook payloads or API responses, troubleshooting OAuth/version-mismatch errors against the hosted MCP, or auditing an existing Shippo integration before a change.

goshippo 2e4b320 2 files · 5.4 KB Updated Sep 17, 2026

File contents

The Shippo MCP is hosted at https://mcp.shippo.com. It is OAuth-only and auto-updates server-side, so there is nothing to install or upgrade on your side. This skill covers what stays your responsibility: API version awareness, webhook payload versioning, and troubleshooting the hosted session.

API version handling

The current Shippo API version is 2018-02-08. Shippo uses a single long-lived API version, and the hosted server manages it for you server-side. You do not set the Shippo-API-Version header yourself when going through the hosted MCP.

What backward-compatibility means in practice:

Most changes are backward-compatible: new optional fields, new resources, additional webhook events. Existing calls keep working.
Breaking changes are rare and announced via release notes.
Because the server picks the version, you don't pin anything client-side. Your job is to handle new fields gracefully (see webhook versioning below) rather than to manage versions.

Shippo API changes are tracked in the API changelog. As of 2026-06, no recent breaking changes affect the workflows covered by this skill set.

Webhook event versioning

Webhook events can include new fields without bumping the API version. To handle them gracefully:

Default to ignoring unknown fields in your webhook handler, never fail-closed on a field you don't recognize.
Subscribe only to the specific event types you need (track_updated, transaction_created, transaction_updated, etc.).
Verify webhook signatures using the Shippo-Signature header per webhook docs.

Troubleshooting the hosted MCP

`401` or `403` errors

The OAuth session has expired or is not authorized. Re-authorize the Shippo OAuth session: in Claude Code, run /mcp and sign in again.

Tools changed or missing after a server update

The hosted server auto-updates, so the tool catalog can shift without any action on your side. Re-list the current tools via shippo_list_tools to see what is available now.

"Not found" errors for objects you expect to exist

Most likely the object does not exist on the authorized account, or it belongs to a different account. Confirm you are signed in to the account that owns the object (re-authorize via /mcp if needed).

Auditing an existing integration

Before making a change to a production integration:

Don't pin anything client-side. The hosted server manages the API version, so there's nothing to pin.
Verify webhook handlers ignore unknown fields.
Review the API changelog for any breaking changes.
Re-list tools via shippo_list_tools after an update to catch renamed or added operations.

---name: upgrade-shippodescription: Guide for Shippo API version changes, webhook payload versioning, and how the hosted MCP server handles updates. Use when reasoning about backward compatibility, handling new fields in webhook payloads or API responses, troubleshooting OAuth/version-mismatch errors against the hosted MCP, or auditing an existing Shippo integration before a change.---The Shippo MCP is hosted at `https://mcp.shippo.com`. It is OAuth-only and auto-updates server-side, so there is nothing to install or upgrade on your side. This skill covers what stays your responsibility: API version awareness, webhook payload versioning, and troubleshooting the hosted session.## API version handlingThe current Shippo API version is **2018-02-08**. Shippo uses a single long-lived API version, and the hosted server manages it for you server-side. You do not set the `Shippo-API-Version` header yourself when going through the hosted MCP.What backward-compatibility means in practice:- Most changes are backward-compatible: new optional fields, new resources, additional webhook events. Existing calls keep working.- Breaking changes are rare and announced via release notes.- Because the server picks the version, you don't pin anything client-side. Your job is to handle new fields gracefully (see webhook versioning below) rather than to manage versions.Shippo API changes are tracked in [the API changelog](https://docs.goshippo.com/changelog). As of 2026-06, no recent breaking changes affect the workflows covered by this skill set.## Webhook event versioningWebhook events can include new fields without bumping the API version. To handle them gracefully:- Default to ignoring unknown fields in your webhook handler, never fail-closed on a field you don't recognize.- Subscribe only to the specific event types you need (`track_updated`, `transaction_created`, `transaction_updated`, etc.).- Verify webhook signatures using the `Shippo-Signature` header per [webhook docs](https://docs.goshippo.com/docs/tracking/webhooks).## Troubleshooting the hosted MCP### `401` or `403` errorsThe OAuth session has expired or is not authorized. Re-authorize the Shippo OAuth session: in Claude Code, run `/mcp` and sign in again.### Tools changed or missing after a server updateThe hosted server auto-updates, so the tool catalog can shift without any action on your side. Re-list the current tools via `shippo_list_tools` to see what is available now.### "Not found" errors for objects you expect to existMost likely the object does not exist on the authorized account, or it belongs to a different account. Confirm you are signed in to the account that owns the object (re-authorize via `/mcp` if needed).## Auditing an existing integrationBefore making a change to a production integration:1. Don't pin anything client-side. The hosted server manages the API version, so there's nothing to pin.2. Verify webhook handlers ignore unknown fields.3. Review the [API changelog](https://docs.goshippo.com/changelog) for any breaking changes.4. Re-list tools via `shippo_list_tools` after an update to catch renamed or added operations.

Frequently asked questions