Pinterest has announced a hosted MCP server that is still in a partner-only alpha, community MCP servers each cover a narrow slice, and the Pinterest API v5 is the surface you can ship a product on today. The API brings scoped OAuth, a refresh token that dies after 60 days without use, and access tiers that decide whether published Pins are even visible. This guide compares the options for an agency agent and shows how to run per-client grants in production.
Your agent works for a social media agency. Every Monday it needs to tell each client which Pins drove outbound clicks last week, pull the trending keywords for their category before the content team plans the next batch, check which boards are thin on fresh Pins, and publish the approved creatives to the right board sections. You go looking for a Pinterest MCP server and find two very different things: an official one Pinterest announced at Cannes Lions that you can't sign up for yet, and a scatter of community servers ranging from an Ads API wrapper to a headless-browser scraper. Pinterest also ships a mature v5 REST API with scoped OAuth. That changes the shape of the decision: the official MCP option is real but gated, the community options each solve a narrow slice, and the first-party option you can actually ship on is the API you wire yourself. Here's how to pick.
Pinterest's official server was announced on June 17, 2026, alongside the Ask Pinterest app, ahead of Cannes Lions. PPC Land's coverage describes it as an alpha that lets external AI tools reach campaign performance data, analytics, and keyword insights, built with partners including PMG, Pacvue, Dentsu, Havas, Innovid by Mediaocean, and Omnicom's Jump450. Pinterest followed with a community announcement on September 22, 2026 that frames it around "AI assistants, copilots, and agentic workflows."
The developer page shows what it will look like. It is hosted, not local: the sample client config points an HTTP transport at https://api.pinterest.com/mcp with a bearer token in the Authorization header. The page names Claude, Cursor, and VS Code as clients, mentions OAuth 2.0 authorization and granular permissions, and lists capability areas: searching Pins, exploring and managing boards, trend discovery, audience and keyword insights, and creating, updating, and optimizing ads content. It names no tools, lists no scopes, and gives no launch date. Until it ships, you can't evaluate its tool surface, only its intent.
Community servers fill the gap, each covering a narrow slice:
The Pinterest API v5 is REST at https://api.pinterest.com/v5, published as an OpenAPI spec (version 5.28.0 at the time of writing). It covers user accounts and their analytics, boards and board sections, Pins and media uploads, Pin and board search, ad accounts, campaigns, ad groups, ads, audiences, ads reporting, catalogs and product groups, trends and keyword insights, and the Conversions API at POST /v5/ad_accounts/{ad_account_id}/events. Lists paginate with a bookmark cursor and page_size.
Auth is OAuth 2.0 in three grants, per Pinterest's authentication docs:
Many organic endpoints also accept an optional ad_account_id. That is Business Access: a token user who holds a role on someone else's ad account can act as that account's owner, for example reading Pin analytics with the Admin or Analyst role. For agencies it is the most important parameter in the API.
The official column is mostly "announced," and that is the honest status. Pinterest's alpha targets agencies and ad-tech partners working on campaign reporting and planning, which overlaps with what an agency agent wants, but you can't see the tool names, you can't test scope behavior, and you can't put a launch date in a project plan.
The community column splits by approach. The Ads server is the most complete for paid media. The scraper is the only one that needs no Pinterest approval, which is also why it should never sit behind a product: it reads public pages, not a customer's account, and it bypasses the platform's terms rather than its API. None of them handles organic analytics or catalogs.
The API column has one empty row that surprises people. Pinterest v5 has no webhooks for organic activity. Nothing tells your agent that a Pin was saved 400 times overnight; the agent asks. The Conversions API runs the other way: you send purchase and lead events to Pinterest.
"Which of the Lumen Home client's Pins published in October drove the most outbound clicks, and which board should get the next batch" on the raw API means calling GET /v5/boards with ad_account_id, walking bookmark cursors through each board's Pins, batching Pin IDs into groups of 100 for the analytics endpoint, keeping start_date within 90 days of today, and handling the fact that Pins created before March 20, 2023 only report lifetime metrics for video and Idea formats. Every intermediate response lands in the model's context.
An MCP server collapses that into named tools the model picks itself, and for the official server, Pinterest would own the schemas. That is the appeal: a marketer opens Claude, connects, and asks. Writing the schema is the hard part. Not the API call.
The tradeoff today is availability and ownership. The official server is gated. Community servers change when their maintainers push, cover narrow slices, and authenticate as whoever pasted the token. An agent tuned against one inherits all three properties.
On the official MCP path, Pinterest's sample config passes a bearer token in a header, and the page mentions OAuth 2.0 with granular permissions. Until the flow is documented, you don't know whether it issues per-user tokens through a standard MCP authorization flow, which scopes it requests, or how long its tokens live. A hosted server that holds a bearer token in a client config file on a laptop is the same custody model as a pasted API key, whatever minted the token.
On the community MCP path, auth is whatever the server reads. The Ads server reads a bearer token from its environment. The seven-tool server runs its own OAuth flow against your app's credentials on localhost, then keeps the token on that machine. The scraper uses no auth at all, which means it can only see what an anonymous visitor sees.
On the direct API path, you get the most complete OAuth story of any surface here. Scopes are explicit and granular: boards:read versus boards:read_secret, pins:write versus pins:write_secret, plus ads:read, ads:write, catalogs:read, user_accounts:read, biz_access:read, and billing:read. A reporting agent can request boards:read,pins:read,user_accounts:read and never hold write access. Access tokens last 2,592,000 seconds (30 days). Pinterest now issues only the continuous refresh token: it expires 60 days after issue, each refresh returns a new one with a new refresh_token_expires_at, and if you miss the window the user must go through the Authorization Code flow again. Apps created before September 25, 2025 must send continuous_refresh=true to get this behavior.
Two quirks follow. First, POST /v5/oauth/token/revoke "only supports tokens issued for system users," per the spec, so you can't revoke an ordinary user's token through the API; you stop using it and let it age out, or the user removes the app from their Pinterest settings. Second, Business Access means a single token can reach many accounts. An agency strategist with Admin on 60 client ad accounts holds one token that, with the right ad_account_id, reads and writes boards and Pins for all 60. What the user can't do, the agent can't do. Everything the user can do across those accounts, the agent can.
In a multi-tenant B2B agent, MCP gives you a credential per user and the direct API gives you a credential per user. In neither case does the path itself solve storage, rotation, or revocation; those are infrastructure problems regardless of which path you choose.
Pinterest sharpens this in two directions. Business Access concentrates reach: the convenient design is one agency staffer's token plus a table of client ad_account_id values, and that token's blast radius is every client the staffer can touch. The alternative is a connected account per client brand, authorized by the client's own business account, so each client can be revoked alone. And the September 14, 2026 data access rule pushes you toward business accounts: apps registered on or after that date get 403 PINNER_DATA_ACCESS_DENIED on get board, list Pins on board, list board sections, and get Pin for personal accounts. Pinterest's explainer says to treat it as an authorization state, not a temporary failure, and not to retry in a loop. Your onboarding flow has to detect a personal account and ask the client to convert it before the agent's first board read.
Recommended reading: OAuth vs API keys for AI agents
On the MCP path, you own the server you run, its version pinning, and its failure modes, because no community server is backed by Pinterest. The official server promises to handle authentication, rate limits, and response formatting, which is exactly what you'd want, once you can use it. Neither path learns about anything that happens in Pinterest between prompts.
On the API path, you own the token lifecycle, pagination, rate limits, and the access tier. Pinterest's rate limits differ sharply by tier:
Watch x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset on responses. The 60-per-minute org_analytics limit is the one an analytics agent hits first: a Monday run across 60 clients that calls account analytics, top Pins, and per-board Pin analytics will queue behind it unless you batch Pin IDs into the 100-per-call analytics endpoint.
The token calendar is the other recurring job. Access tokens die at 30 days and continuous refresh tokens at 60, so a client who authorized in August and whose account the agent didn't touch through October needs a fresh consent. A daily job that refreshes every token older than 25 days is not optional.
Use a Pinterest MCP server when:
Use the Pinterest API when:
Both paths hand you a Pinterest credential per user. Neither hands you a vault. An agency platform serving 30 agencies with 60 client brands each holds 1,800 Pinterest grants if it isolates by client. Each one carries a 30-day access token and a 60-day continuous refresh token that must be refreshed on time or lost, stored encrypted, kept out of logs and LLM context, mapped to exactly one client at one agency, and dropped when the client leaves. Pinterest's API can't revoke ordinary user tokens for you, so "dropped" means your system stops using it and forgets it.
The MCP path doesn't reduce the count. It moves tokens into client config files, where nobody can list or refresh them centrally, and a 60-day refresh window quietly expires on every laptop that wasn't opened in time. The tempting shortcut on the API path is one strategist's token plus Business Access across every client. Fewer secrets, larger blast radius: that token reaches all 60 brands, and when the strategist leaves the agency, so does the only credential the agent was running on.
Scalekit's pinterest connector runs the OAuth flow per user, stores each token in the token vault, refreshes it before Pinterest's windows close, and resolves it at request time, so the MCP vs API decision doesn't change your auth infrastructure. Your agent passes an identifier; credentials never touch the agent runtime or the LLM context.
Recommended reading: how to handle token refresh for AI agents
Scalekit's pinterest connector is an API-path connector built by Scalekit with 72 tools: 50 read-only, 19 write, and 3 destructive. It covers boards and board sections, Pins and product tags, media uploads, user account analytics and top Pins, Pin analytics, search, trends and related terms, catalogs, feeds, local stores, product groups, and catalog reports. Business Access tools accept an optional ad_account_id, and the token user must hold an appropriate role on that ad account. The core set for an agency reporting agent:
The connector authenticates with OAuth 2.0 through your own Pinterest app; Scalekit stores and refreshes user tokens.
In the Scalekit dashboard, go to AgentKit > Connections, create a Pinterest connection, and copy its redirect URI. In Pinterest's developer portal, register your app under My apps and add that redirect URI. Enter the app's client ID (the App ID) and client secret on the Scalekit connection. The name you give the connection is the connection_name your code passes, and the string must match the dashboard exactly. This is the most common integration error. Copy SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, and SCALEKIT_CLIENT_SECRET from Developers > API Credentials into .env. Plan for Pinterest's Standard access review before launch: on Trial, Pins your agent creates stay invisible to everyone but the creator. See the connector docs.
The scenario uses one connected account per client brand, authorized by the client's own Pinterest business account, so the identifier encodes both the agency and the client. get_or_create_connected_account returns that account. If it is not ACTIVE, get_authorization_link returns the Pinterest consent link the client opens once. Then pinterest_user_account_get confirms which Pinterest account the grant belongs to, so a client who approved from a personal profile instead of the brand's business account is caught before the agent reads a board and hits PINNER_DATA_ACCESS_DENIED.
This is not a catalog load. The agent asks for the tools this client's connected account is authorized to call, then narrows them to the seven a read-only reporting assistant needs. Pinterest scopes already separate pins:read from pins:write, but your connection may request both because the same grant also powers publishing. This list is where the reporting agent's reach gets smaller than the grant: pinterest_pin_create, pinterest_board_create, and pinterest_catalog_items_batch_create, which can delete catalog items in bulk, never reach the model, so it cannot publish to a client's board or wipe a product feed while answering a question about saves.
The loop runs until the model stops requesting tools. Every call executes with this client's Pinterest grant and sees only that brand's boards and Pins. The system prompt carries the details that trip models up on this API: bookmark paging, the 90-day analytics window, the 100-Pin batch limit, and the analytics rate limit.
For pipelines, skip the model. execute_tool runs one tool with a fixed input and returns data plus an execution_id you can log. This job runs every Monday at 06:00 for every client brand an agency manages. Pinterest has no webhooks, so a schedule is the trigger. It pulls last week's account totals with pinterest_user_account_analytics_get, and it treats a PINNER_DATA_ACCESS_DENIED response as an onboarding problem to surface, not an error to retry. Each client's numbers come from that client's own grant, so one revoked client fails alone.
Board-level detail needs every Pin ID on the client's active boards, which means walking bookmark cursors. The function below collects them with pinterest_board_pins_list at the maximum page size of 250, so a board with 1,200 Pins costs five calls against the 1,000-per-minute org_read limit instead of 48 at the default of 25.
Feed those IDs to pinterest_pins_analytics_list in groups of 100, and a 1,200-Pin board needs 12 analytics calls, well inside the 60-per-minute org_analytics limit.
Publishing is where an agency pipeline most often needs exact control: a human approves the creative, then code publishes it, no model in between. Here it is against the API directly, with the refresh you own on this path. The token refresh uses HTTP Basic with your app credentials and returns a new continuous refresh token that must replace the old one. Scalekit custom connectors cover authenticated REST calls the prebuilt tools don't.
Every value in that snippet is something Scalekit otherwise holds for you: the app secret, the refresh token, the new refresh token that must be written back atomically, and the 60-day deadline. Lose a refresh write during a deploy and the client re-consents.
An agency reporting agent rarely stops at Pinterest. It reads the numbers, then posts a digest to the client's Slack channel. Load all 72 pinterest tools and the model holds pinterest_pin_create, pinterest_board_create, and pinterest_catalog_items_batch_create while answering "how many saves did we get last week." At roughly 200 tokens each, 72 tools is about 14,400 tokens before the agent does any work, and the model is choosing from a decision space it doesn't need. The fix is not better prompting. It is surface reduction. A Scalekit virtual MCP server declares exactly which tools an agent role can see across connections, and session tokens keep each run bound to one user's connected accounts. It is also the hosted Pinterest MCP endpoint you can use today, while Pinterest's own server is in alpha. Docs: set up a virtual MCP server.
One server definition serves every client brand at every agency. Before each run, check that the client's accounts are active and mint a short-lived session token scoped to them. Any MCP client that speaks Streamable HTTP can connect; this example uses langchain-mcp-adapters (pip install langchain-mcp-adapters) and passes the token as a Bearer header.
The agent sees five tools instead of 72 plus everything Slack exposes. The endpoint is static; the identity is per-user. A strategist can point Claude or Cursor at the same server URL, and each run acts as one client brand through that client's own OAuth grant instead of a bearer token pasted into a config file. When Pinterest's official server reaches general availability, this pattern doesn't change: a vendor MCP server becomes another connection, and the session token still decides whose credentials a run uses.
Every execute_tool call returns an execution_id, and every execution is attributed to a connected account, which maps to one client brand at one agency. When a client asks which run published a Pin to the wrong board at 03:00 or why last Tuesday's report showed zero saves, the answer is a lookup, not an investigation.
The shared-token designs are weaker by construction. A community MCP server reads one token, so every action looks, to Pinterest, like the token's owner did it by hand. Business Access compounds that: if five strategists drive one agent through one senior strategist's token, Pinterest's records show the senior strategist acting on 60 client accounts, and nothing anywhere says which colleague asked or which client's request it served. With no webhooks, there isn't even an inbound event stream to reconcile against; your own logs are the only record of who did what. Shared credentials are a single-user solution. They do not survive a second user.
Recommended reading: audit trails for agent auth
If your agency is in Pinterest's MCP alpha and the work is campaign reporting from Claude, use it and watch for the launch details, because a Pinterest-maintained server will eventually be the lowest-maintenance way to ask questions about ad accounts. If your agent is one marketer's assistant for their own account, a community server works for the slice it covers, as long as someone pins and reads its code. If you are building that assistant into a product for many brands or agencies, build on the Pinterest API v5 with per-client OAuth, Standard access, and a scheduler, because it is the only surface today with scoped consent, organic analytics, publishing, and catalogs. Either way, you hold a Pinterest grant per client whose refresh token dies at 60 days and whose reach can extend across every account Business Access touches, and that's what needs production-grade infrastructure.
Pinterest has announced one, hosted at its API domain, but as of November 2026 it is an alpha with agency and ad-tech partners such as PMG, Dentsu, Havas and Pacvue. Its developer page asks you to sign up to be notified at launch and publishes no tool list, scopes or launch date.
Three cover narrow slices: a 23-tool server for the Pinterest Ads API, an unofficial scraper that reads public pages with a headless browser and uses no account data, and a seven-tool server for boards and Pins that runs OAuth against a localhost redirect for one user. None covers organic analytics or catalogs.
Access tokens last 30 days. Pinterest issues a continuous refresh token that expires 60 days after issue, and each refresh returns a new one, so a grant used regularly lasts indefinitely but one left alone for 60 days needs new consent. The revoke endpoint only supports system user tokens.
New apps start on Trial access with 1,000 requests per day, and boards and Pins they create are visible only to the creator. Standard access raises limits to per-user, per-category budgets and requires a video demo of a working OAuth integration, which can take weeks to review.
Many endpoints accept an optional ad account, so a token user with a role on someone else's ad account can act for that account's owner. It lets one agency strategist's token reach every client they hold a role on, which is convenient and concentrates the blast radius in one credential.
Scalekit's Pinterest connector runs the OAuth flow through your own Pinterest app, stores each grant in a vault and refreshes it before Pinterest's windows close. It exposes 72 tools, 50 read, 19 write and 3 destructive, and works well with one connected account per client brand, served through a virtual MCP server.
Browse the Scalekit Pinterest connector and the Pinterest connector docs with the full tool list. See Scalekit pricing, or talk to us.
