Porter Metrics MCP Server

Overview

Porter Metrics MCP Server exposes Porter's marketing platform as a Model Context Protocol server. Once connected, an agent can:

Discover and connect the data sources a customer uses — 32 connectors across advertising (Meta, Google Ads, TikTok, LinkedIn, Microsoft, Pinterest, X, Apple, DV360), social insights, GA4, Search Console, Shopify, Amazon Seller, Stripe, HubSpot, Klaviyo, Mailchimp, ActiveCampaign, plus BigQuery, Snowflake, PostgreSQL and Google Sheets.
Query data ad-hoc — across one connector or blended across many — and return rows ready to render.
Save blends (named cross-connector queries) and schedule recurring exports to BigQuery or Google Sheets.
Create, edit and share hosted reports: live dashboards deployed behind their own URL.
Reach the long tail of marketing operations through an action catalog of 750+ operations: campaign management and write-backs on the ad platforms, AI creative generation (image, video, voiceover), CRM and email marketing, e-commerce, SEO and web research.

The MCP is a thin, audited façade over Porter's existing backend. Every call is bound to the authenticated user's Porter identity and respects their company role assignments and license entitlements.

Requirements

A Porter Metrics account. Sign up at portermetrics.com if you don't have one.
At least one authorized data source (Facebook Ads, Google Ads, etc.) on your account — or authorize one from the conversation with connect_account.
An MCP-compatible client: Claude Desktop, Claude Web (Connectors), ChatGPT (Codex), Gemini, or the @modelcontextprotocol/inspector.
For recurring exports: a connected destination — BigQuery or Google Sheets, set up in-app or from the conversation.

Connect Porter to your client

Porter Metrics MCP Server is a remote server. There is nothing to install locally — your client opens an OAuth flow to Porter and from then on calls the public endpoint.

Endpoint

https://mcp.portermetrics.com/mcp

Claude (Desktop / Web)

Open Settings → Connectors → Add custom connector.
Paste the endpoint URL above.
Click Connect. A browser tab opens Porter's login page.
Sign in with the same email you use at portermetrics.com (Google SSO is supported).
Approve access. The tab returns to Claude and the Porter Metrics MCP Server becomes available.

Optional: the install page also offers a downloadable Claude skill that teaches the agent Porter's recommended workflows.

ChatGPT / Codex

Open Connectors → Add MCP server.
Paste the endpoint URL and choose OAuth as the authentication method.
Complete the Porter login redirect.

MCP Inspector (for developers)

npx @modelcontextprotocol/inspector https://mcp.portermetrics.com/mcp

How authorization works

Porter Metrics MCP Server is a resource server in OAuth terms. It speaks RFC 9728 and discovery metadata is published at /.well-known/oauth-protected-resource. The actual identity provider is Amazon Cognito (with Google federation), the same one that powers app.portermetrics.com.

One Porter login covers the MCP. If you're already signed in at app.portermetrics.com, Claude inherits that session through SSO.
Per-connector authorizations are separate. Authorizing Porter to access your Facebook Ads account, for example, is a different OAuth handshake the agent will offer when needed (connect_account). The MCP itself does not see or store your Facebook tokens; Porter does, server-side.
Token storage. The MCP server encrypts persisted OAuth state (DCR clients, refresh tokens) at rest using AES Fernet. Encryption keys can be rotated without invalidating live sessions.

Available tools

The connector exposes 28 tools in five groups: management, analytics, reports, actions and support. Each tool carries an MCP title annotation plus readOnlyHint / destructiveHint / idempotentHint annotations so clients can decide when to ask you for confirmation.

read-only runs without confirmation. additive write creates state. destructive always prompts for confirmation (deletes a blend, modifies a live campaign, etc.). idempotent is safe to retry.

Management

Tool	Type	What it does
`whoami`	read-only	Identifies the authenticated user and the company they act under.
`list_connectors`	read-only	Returns Porter's catalog of data sources, destinations and integrations, searchable and filterable.
`list_accounts`	read-only	Lists the accounts the user can act on for a connector — already connected to Porter (billing applies) or available in the third party but not yet registered. Paginated; pass `query=` for fuzzy search. Drop-in input for `query_data(accounts=…)`.
`connect_account`	additive write	Starts the OAuth flow (or returns manual setup instructions) to authorize a connector or destination. Also connects BigQuery as a data source via `role="source"`.
`disconnect_account`	destructive	Disconnects a previously authorized third-party integration.
`get_knowledge`	read-only	Searches Porter's knowledge base: skills, step-by-step workflows, error→fix patterns and FAQs.
`prepare_upload`	additive write idempotent	Returns a one-time signed URL to upload heavy payloads (media assets, CSVs) referenced by later calls.

Analytics

Tool	Type	What it does
`list_fields`	read-only	Returns the catalog of queryable metrics and dimensions, per connector or for a saved blend.
`query_data`	read-only	Runs an ad-hoc query over one or more connected accounts — cross-connector when several are passed — with filters and date ranges. Returns rows.
`bigquery_join`	read-only	Combines 2–5 BigQuery tables in an ephemeral join (INNER/LEFT/RIGHT/FULL) that can be queried like any source.
`query_blend`	read-only	Re-runs a saved blend by ID against live data.
`list_blends`	read-only	Lists saved blends, paginated, filterable by name.
`get_blend`	read-only	Returns a blend's definition, schema, attached exports and recent executions.
`create_blend`	additive write	Persists a new saved blend (a named cross-connector query) and warms its schema cache.
`update_blend`	additive write idempotent	Edits an existing blend; can re-warm the schema.
`delete_blend`	destructive	Deletes a blend. Attached exports are removed with it.

Reports

Reports are self-contained HTML/CSS/JS bundles that Porter deploys behind their own URL. The agent writes the frontend and a structured chart config; Porter packages it, hosts it, and enforces sharing/auth on every request.

Tool	Type	What it does
`list_reports`	read-only	Lists the company's hosted reports, paginated, searchable by name.
`get_report`	read-only	Returns a report's metadata, structure and source-bundle download URL without rendering it (fast path).
`preview_report`	read-only	Renders the report against live data and returns diagnostics. Slow by design (5–30 s).
`create_report`	additive write	Creates a hosted report from a base template and returns its URL. Private by default until shared.
`edit_report`	destructive	Edits an existing report: download → modify → rebuild → redeploy. Sharing settings are unchanged.
`duplicate_report`	additive write	Clones a report onto new source accounts — the fastest way to roll one template out across clients.
`share_report`	additive write	Sets visibility and recipients (any email, per-recipient roles). Applies immediately, no redeploy.
`delete_report`	destructive idempotent	Deletes a hosted report. Its URL stops resolving.

Actions

Tool	Type	What it does
`list_actions`	read-only	Semantic search over the 750+ operation catalog: describe the task in plain language and get ranked actions with their parameter schemas.
`execute_action`	destructive	Runs a catalog action against the user's authorized account. Marked destructive because many actions modify state on the third-party platform; your client will ask for confirmation.

Support

Tool	Type	What it does
`report_bug`	additive write	Files a bug with Porter's engineering team straight from the conversation. Most reports are fixed within 24 h.
`request_feature`	additive write	Sends a feature request to the product team (asks for your explicit approval first).

The action catalog

The 28 tools above are the fixed surface. The rest of Porter's capability — the long tail of marketing operations — lives in a catalog of 750+ actions across ~40 categories, reached through list_actions / execute_action. The agent searches by intent ("pause underperforming campaigns", "generate a product video"), inspects the returned parameter schema, and executes.

Categories include (non-exhaustive):

Creative generation (creative.*, audio.*) — a built-in AI studio: generate and edit images, produce video with native audio, text-to-speech voiceovers and voice design. Generated assets are served from a stable URL, ready to drop into a report or an ad.
Ad-platform management — create and edit campaigns, ad sets/groups, ads, budgets and audiences on Google Ads, Meta, TikTok, LinkedIn, Microsoft, Pinterest, X, Apple Ads and DV360.
Exports & schedules (blend_export.*, report_email_schedule.*) — attach recurring BigQuery/Sheets exports to a blend, or email a report on a cron schedule.
CRM & email marketing — HubSpot, Klaviyo, Mailchimp, ActiveCampaign.
E-commerce — Shopify, Amazon Seller: products, orders, customers.
SEO, search & web research — keyword/SERP intelligence, Search Console, web scraping.

Every action result comes back in a fixed envelope — {status, result, message, knowledge, follow_up} — where knowledge carries recovery guidance when something needs fixing (an expired token, a missing permission), so the agent can self-correct.

Typical flows

Brand-new account: query Facebook Ads for the last 7 days

list_connectors(query="facebook") — confirm Facebook Ads is supported.
list_accounts(connector="facebook-ads") — empty means nothing is authorized yet; rows with connection_status="available" are accounts already authorized in the third party but not yet registered in Porter.
connect_account(connector="facebook-ads") — the agent hands you a URL. You open it; Porter runs the OAuth flow; the page returns you to your client. Re-run list_accounts to see the new accounts.
query_data(accounts=[…], fields=[…], date_range="last_7_days") — rows. Picking an available account registers it on the first query (billing starts then).

Returning user: query an already-known account

list_accounts(query="…") — find the account by name or ID.
query_data(accounts=[…], fields=[…], date_range={…}) — rows.

Build and share a live dashboard

list_fields / query_data — explore the data and settle the metrics.
create_report — the agent writes the dashboard and gets back its hosted URL (private by default).
preview_report — render against live data, iterate with edit_report until it's right.
share_report — grant access to specific emails or roles; duplicate_report to roll the same template out to another client's accounts.

Recurring export to BigQuery or Google Sheets

connect_account with the destination if you haven't yet (BigQuery supports OAuth or a service-account key).
create_blend(name, …) — save the cross-connector query you want exported.
list_actions(task="schedule a recurring export") → execute_action("blend_export.create", …) — attach the destination and cron. Your client prompts for confirmation, then the export runs once immediately.

Data handling & privacy

Authorization scope. The MCP never sees passwords. It receives a short-lived Cognito id_token for the authenticated Porter user and uses it to call Porter's existing backend. Third-party tokens (Facebook, Google, Shopify, …) live exclusively on Porter, encrypted at rest.
Conversation data. Porter Metrics MCP Server does not request access to your chat history, memory, conversation summaries or files. The server only receives the tool calls your client decides to make and the parameters they carry.
Telemetry. Server logs record tool name, latency and error type — never tool arguments or response bodies — for diagnostics.
Data residency. Calls hit Porter's existing US-region infrastructure. BigQuery exports go to whatever region you select when configuring the destination dataset.
Account ownership. The MCP filters returned accounts by the companies in which your Porter user has a role. You cannot see accounts that live in companies you do not belong to.

The full Porter Privacy Policy and Terms of Service apply to all use of the MCP.

Common errors and how to recover

Every tool returns errors in a structured envelope — {error_type, message, hint} — and the hint usually contains the exact recovery step. The most common cases:

You see	What it means	What to do
An empty `list_accounts` result + a `message` mentioning re-authorization	The third-party token (e.g. Facebook) is expired or revoked for one of your authorizations.	Run `connect_account` with the affected connector and re-authorize. Retry.
"Porter has no role assignments on file for this user"	Your Porter user is signed in but has no company role yet.	Sign in at app.portermetrics.com and complete onboarding (create or join a company).
"No third-party authorizations found"	You're signed in but haven't authorized any connector yet.	Use `connect_account(connector=…)`.
HTTP 401 from any tool call	The MCP access token expired.	Disconnect and reconnect the Porter Metrics MCP Server in your client; the OAuth flow will refresh.
`account_not_allowed` when duplicating or editing a report	The target accounts belong to a company your user has no role in.	Pick accounts from `list_accounts` (they're pre-filtered to what you can use), or get access to that company in Porter first.
A failed `execute_action` with a `knowledge` block	The action ran into a recoverable condition (missing param, expired 3P token, platform-side rejection).	Follow the `knowledge`/`follow_up` guidance in the response — it's generated for that exact failure.

Limits

Query rows. query_data accepts limit with no fixed upper bound; very large queries may be slower because Porter walks the third-party API in real time.
Field catalog. Large per-connector catalogs are truncated with a hint telling the agent how to narrow the search.
BigQuery joins. bigquery_join combines 2–5 tables per join.
Report preview. preview_report renders against live data and typically takes 5–30 s; get_report is the fast path when you don't need rendered output.
Schedules. Recurring exports and report emails accept cron expressions for fine-grained control.
Rate. Porter applies the same per-account rate limits that govern the rest of the platform. The MCP does not impose additional caps.

Support

If something is wrong or missing:

Tell the agent — the report_bug and request_feature tools file directly with Porter's team from the conversation.
Email support@portermetrics.com with a short description of the tool call you attempted and the response you saw.
Live chat at portermetrics.com (bottom-right) is the fastest path during business hours.
For sales / commercial questions: portermetrics.com/en/free-report-setup.

When reporting an MCP bug, please include: the client name (Claude Desktop / Web / ChatGPT / …), the timestamp, the tool name, and the exact error message.