SavePinner MCP developer guide

Validate Pinterest URLs before your application uses them

Pinterest links arrive in several forms: full Pin URLs, localized hosts, profile and board URLs, and shortened pin.it links. Treating every URL that contains the word “pinterest” as valid creates routing bugs and can turn a media workflow into an unsafe open redirect.

Use an exact host allowlist

Parse the value with the platform URL parser, require HTTPS, and compare the normalized hostname with an explicit allowlist. A suffix or substring check is insufficient because names such as pinterest.com.example.org and notpinterest.com are controlled by unrelated operators. For full URLs, accept Pinterest country hosts only when the registered domain remains pinterest.com. Treat pin.it as a separate short-link host.

const candidate = new URL(input);
if (candidate.protocol !== "https:") throw new Error("HTTPS required");

const host = candidate.hostname.toLowerCase();
const isFullPinterest = host === "pinterest.com" || host.endsWith(".pinterest.com");
const isShortPinterest = host === "pin.it";
if (!isFullPinterest && !isShortPinterest) throw new Error("Unsupported host");

Classify the path before extracting identifiers

A Pin URL normally uses /pin/{numeric-id}/, but profiles, boards, and idea pages have different path shapes. Split the decoded pathname into non-empty segments, classify the resource, and then apply rules for that resource. Never treat the first sequence of digits anywhere in a URL as a Pin identifier. Query parameters can contain tracking values that look like IDs.

Normalization should remove fragments and known tracking parameters, standardize the host, and produce a predictable trailing slash. Keep the original value in diagnostic output so an operator can trace how the canonical form was produced.

Resolve short links with strict redirect rules

A pin.it URL cannot be converted safely by string replacement. A service that needs the final Pin must make a network request, reject redirects to hosts outside the allowlist, cap the number of hops, and apply short timeouts. Validate every redirect destination before following it. The SavePinner MCP tools deliberately make no outbound requests, so they classify short links without resolving them.

Boundary: URL validation confirms structure and ownership of the hostname. It does not prove that a Pin exists, that a media file is public, or that the person requesting it has permission to use it.

Keep media-host validation separate

After an application retrieves Pin metadata, validate media URLs with a second allowlist and a separate policy. Do not reuse Pinterest page-host rules for image or video delivery hosts. Enforce response size limits, content types, redirect limits, and request timeouts before proxying or downloading a file. This separation makes the trust boundary visible and easier to test.

Test adversarial and ordinary inputs

A useful test table includes a canonical Pin, a localized Pinterest host, tracking parameters, a pin.it short link, a profile, a board, malformed text, an HTTP URL, a deceptive suffix, and credentials embedded before the hostname. Assert both acceptance and the exact normalized result. Property tests can add random casing, fragments, and query parameters without replacing the small set of readable regression cases.

Use the public MCP endpoint

SavePinner MCP exposes three read-only tools: parse_pinterest_url, normalize_pinterest_url, and is_pinterest_url. Connect a Streamable HTTP client to https://savepinner-pinterest-url-mcp.chenxuanshimo.workers.dev/mcp. The endpoint requires no authentication, stores no request state, and performs no media download.

For people who need to inspect media exposed by a public Pin in a browser, use the Pinterest image downloader. Always respect the creator’s rights and the terms that apply to the content.