The short answer
If you are shopping for a marketing analytics API for AI agents, DuckDive's is an MCP server rather than REST. Point any MCP client at https://api.duckdive.ai/mcp: it speaks streamable HTTP and signs users in with OAuth 2.0, using PKCE (S256) and dynamic client registration, so there is no API key to issue or rotate.
Each data tool reads a single website_id, most accept one of six fixed time_range windows, and ranked lists stop at 100 rows. A report spanning many sites is a loop your code owns.
- Read access is the
mcp:readscope; setup and refresh calls needmcp:actionsplus an admin seat. - Each website keeps its own imported history, so a loop across sites reads history DuckDive already stored instead of fetching a fresh Google report.
- Discover endpoints from the metadata documents instead of hard-coding them.
Protocol reference: endpoint, transport and sign-in
DuckDive keeps the Google sign-in, the six source integrations and the stored history on its side. You integrate with one MCP server that answers for one website at a time. The whole surface fits on this card.
- Endpoint
https://api.duckdive.ai/mcp, per DuckDive's agent setup guide.- Transport
- Streamable HTTP: one POST per JSON-RPC message; the reply is JSON or a request-scoped event stream.
- Unauthenticated call
- HTTP 401 with
invalid_tokenand aresource_metadataURL in theWWW-Authenticateheader. - Authorization server
https://api.duckdive.ai/, metadata at/.well-known/oauth-authorization-server.- Grants
- Authorization code and refresh token.
- PKCE
- S256 only.
- Client registration
- Dynamic, at
/register. - Revocation
/revoke.- Scopes
mcp:readandmcp:actions.- API key
- None. The guide says never to paste in a key or a hand-made Authorization header. The Bearer header carries the OAuth token your client got at sign-in.
The streamable HTTP rules come from the MCP transport specification: send an Accept header listing application/json and text/event-stream, and handle both. The 2026-07-28 revision dropped protocol-level sessions and wants an MCP-Protocol-Version header on every POST, so let an MCP SDK negotiate the version.
HTTP/2 401 www-authenticate: Bearer error="invalid_token", error_description="Authentication required", resource_metadata="https://api.duckdive.ai/.well-known/oauth-protected-resource/mcp"
Connecting your own client, step by step. Most SDKs do this for you; this is what runs underneath.
-
Follow the 401 to the metadata
The
resource_metadataURL names the authorization server. Its RFC 8414 metadata document lists the authorization, token, registration and revocation endpoints. Read them; do not hard-code them. -
Register your client once
POST your
client_name,redirect_urisandgrant_typesto the registration endpoint, as RFC 7591 describes, and keep the returnedclient_id, keyed by issuer. -
Send the user through the browser with PKCE
Make a verifier of 43 to 128 characters and send its base64url SHA-256 hash as the S256 challenge, per RFC 7636, with
resourceset to the MCP endpoint. The user selects Continue with Google (or Allow, if already signed in) and decides whether Also allow actions stays ticked. -
Swap the code for tokens
Send the code and verifier to the token endpoint. The refresh token goes in a secret store, never a repo or a log.
-
List the tools before calling any
Validate arguments against the schemas
tools/listreturns, then calllist_websitesas a smoke test.
Expect one wrinkle if you read the protocol closely. As of November 2026 the authorization chapter of the MCP spec (its 2026-07-28 revision) tells clients they SHOULD support Client ID Metadata Documents and keeps dynamic registration only for backwards compatibility, labelled deprecated. Because DuckDive still advertises /register, a client that walks the spec's registration options in order lands on that fallback and connects.
Ask your agentCall tools/list on the DuckDive server and give me a markdown table: tool name, required arguments, optional arguments with their defaults, and the allowed values for time_range. Mark the tools that change anything in my account.
Tools it calls tools/list (a protocol method, not a DuckDive tool)
Scopes and what each one allows
Two scopes, and a reporting job or chat bot needs only the first. A token without mcp:actions cannot add a website when a prompt goes sideways.
| What your code calls | mcp:read | mcp:actions |
|---|---|---|
| Six sources' data tools | Yes, the whole reporting surface | Not needed |
| list_websites, get_website, search, fetch | Yes | Not needed |
| get_sync_status, get_setup_status | Yes, read-only status | Not needed |
| refresh_website_data | No | Yes, admin seat only |
| add_website, connect_website_sources | No | Yes, admin seat only |
| create_scheduled_report | No | Yes, admin seat only; mails the signed-in user only |
Scope names from the authorization server metadata; tool-to-scope mapping inferred from the connector guide, pending confirmation. Checked November 2026.
Two layers stack. The scope limits the token; the DuckDive role limits the person. Actions need an Agency Admin or Client Admin seat, and team members stay read-only whatever the client requests. Under the spec, missing scope comes back as a 403 with error="insufficient_scope", and the client re-authorizes asking for old plus new scopes.
Tool contracts: inputs, ranges and row limits
Arguments as the server exposed them on November 16, 2026. At runtime, tools/list wins over this table.
| Tool | Inputs | Limits |
|---|---|---|
| list_websites | search, limit, offset | Default 50, maximum 100 per page |
| get_website | website_id | One site's name, URL and linked sources |
| get_search_console_summary | website_id, time_range | Clicks, impressions, CTR, position over time |
| get_ga4_landing_pages | website_id, time_range, limit | Default 25, maximum 100 rows |
| get_sync_status | website_id | Per source: ready, importing or failing, and recency |
| refresh_website_data | website_id, source, days | 1 to 30 days; once per site per 15 minutes |
Source: tool schemas returned by the DuckDive MCP server, read November 16, 2026.
website_id is an integer you get from list_websites or search. time_range is an enum: last7days, last14days, last30days, last90days, last6months or last12months, with last30days as default. No start and end dates, no calendar months, nothing past 12 months. Yext reviews and Local Falcon rankings take no range.
The silent default
Omit time_range and you silently get 30 days. Make it required in your wrapper.
Plan the call order first. "Which landing pages lost search clicks and conversions" sounds like one call, but it spans two sources and no tool returns a diff. An agent drafts that plan well:
Ask your agentWhich DuckDive tools would I need to answer 'which landing pages lost search clicks and conversions', and in what order?
Tools it calls list_websites get_sync_status get_search_console_pages get_ga4_landing_pages
A good plan pulls both page lists for two windows, joins them on URL path, and admits the windows overlap. Response fields are not published as a schema, so type them from a live response:
Ask your agentGenerate a TypeScript type for the rows get_ga4_landing_pages returns, based on a real response from my account.
Tools it calls list_websites get_ga4_landing_pages
The 100-row cap bites on ranked lists. If a response holds exactly as many rows as your limit, mark the list as possibly cut off; the tail beyond row 100 is not reachable.
Fanning one question out across many websites
There is no portfolio endpoint. Forty sites means forty calls, each with its own website_id. Forty calls is tolerable because none of them waits on a live fetch: each one reads that site's history on DuckDive's side.
The loop that holds up:
- Page the roster.
list_websiteswithlimit100, steppingoffsetuntil a page comes back short. - Gate on freshness.
get_sync_statusper site; flag sources that are importing or failing. - Bound concurrency. A small worker pool; rate limits are not published, so start low.
- Collect errors per site. One failure lands in an array, not an aborted run.
- Merge last, label the window. Every output row carries the
time_rangeit came from.
const roster = await pageAll("list_websites", { limit: 100 });
const results = await pool(roster, 4, async (site) => {
const sync = await call("get_sync_status", { website_id: site.id });
if (!isReady(sync, ["gsc"])) return { website_id: site.id, skipped: "gsc not ready" };
const gsc = await call("get_search_console_summary",
{ website_id: site.id, time_range: "last30days" });
return { website_id: site.id, ...sumClicksAndPosition(gsc) };
});
One maths trap: average position is not additive. Weight each period's position by its impressions before combining, or quiet days count as much as busy ones.
To prototype the loop with an agent before coding it:
Ask your agentList every website I can access, then call get_search_console_summary for each with last30days and return JSON with website_id, clicks and average position.
Tools it calls list_websites get_search_console_summary
Why stored data matters at forty sites is traced in the stored-history versus live-API comparison.
Worked example: a weekly digest that loops over every website
Every Monday a small Node service writes one JSON file that a chat formatter and an email template both read. For week over week, it pulls get_ga4_overview for last14days, which returns days, and splits it in two.
Build the Monday digest for every website on the account: last 7 days of search clicks and position, GA4 sessions and conversions against the 7 days before, and flag any site with stale data.
list_websitesone page, three sitesget_sync_statuseach site; Tidewren's GA4 still importingget_search_console_summaryeach site, last 7 daysget_ga4_overviewGullwing and Meadowmint, last 14 days, split into two weeks
Two of three sites complete. Meadowmint Tea needs a look: sessions and conversions both fell week over week.
{
"window": "last7days",
"sites_total": 3,
"sites_complete": 2,
"sites": [
{
"website_id": 311,
"name": "Gullwing Cycles",
"search_clicks": 2940,
"avg_position": 11.6,
"sessions": 6180,
"sessions_prev": 5870,
"sessions_change_pct": 5.3,
"conversions": 142,
"conversions_prev": 131,
"conversions_change_pct": 8.4
},
{
"website_id": 312,
"name": "Meadowmint Tea",
"search_clicks": 1215,
"avg_position": 8.9,
"sessions": 3040,
"sessions_prev": 3610,
"sessions_change_pct": -15.8,
"conversions": 61,
"conversions_prev": 77,
"conversions_change_pct": -20.8,
"flag": "declining"
},
{
"website_id": 318,
"name": "Tidewren Pottery",
"search_clicks": 488,
"avg_position": 17.3,
"sessions": null,
"conversions": null,
"partial": "ga4 importing"
}
]
}
Tidewren's GA4 fields are null, not zero, so the formatter prints "importing" instead of a fake 100% drop.
sites_complete sits at the top so consumers say "2 of 3 sites" before ranking anything, and prior values ship beside each change so readers can check the maths. Field meanings, including conversions versus GA4's key events, are on the GA4 source page.
Run that loop against your real sites
Sign in once, link a site's Google sources, and your first tools/list call shows the exact schemas this page describes.
Free for 2 sites · No credit card
Worked example: a team chat bot that answers "how is this site doing?"
Here your bot process is the MCP client and an LLM picks the tools. Your code, not the model, decides the token, the allowed tools and the answer length. Expose only read tools.
@sitebot how is meadowmint doing?
list_websitessearch "meadowmint", one matchget_sync_statusGA4 and Search Console readyget_ga4_overviewlast 30 daysget_search_console_summarylast 30 daysget_ga4_landing_pageslast 30 days, top 10 by sessions
Meadowmint Tea, last 30 days: 14,860 sessions and 312 conversions, a 2.1% conversion rate. Search brought 5,420 clicks at an average position of 9.2. The weak spot is the matcha collection: lots of visits, few orders.
| Landing page | Conv. rate |
|---|---|
| /collections/matcha | 0.9% |
| /blog/cold-brew-ratios | 0.5% |
| /products/sampler-tin | 3.9% |
Want last 7 days, or the search queries behind these pages?
The bot checked sync status before quoting numbers and offered a follow-up instead of dumping rows. Two decisions remain yours:
- Whose token. It acts as the signed-in user and sees every site they can. Use a read-only team-member seat.
- Who may ask. Everyone in the channel borrows that seat, so pick channels with care.
Website names, page paths and search queries in tool results come from outside your company, so treat them as data, never instructions. The guide on connecting an AI agent to analytics safely covers that in full.
Building on Google's APIs yourself: what you take on
Calling Google directly is a real option. Price the work first, because most of it is not the report.
| Job | On DuckDive | Google's APIs directly |
|---|---|---|
| Google sign-in for other people | Done, DuckDive's sign-in | Yours, your OAuth app and its review |
| What a question costs at Google | Not a live call, reads stored data | Per property, 429 when a bucket empties |
| Google Ads access | Yes, account-level summary | Access level per Cloud project |
| Local Services Ads | Yes, leads, charged leads, spend | Partly, needs a manager account |
| Yext and Local Falcon | Same pattern, per website | Two more vendors, two more auth flows |
| History store | Kept per website | Yours, tables, backfills, schedulers |
| Depth on one property | Partly, fixed ranges, 100 rows | Better, any dimension, any dates |
Sources: Google's pages on OAuth app verification, GA4 Data API quotas, Google Ads API access levels and Local Services reporting, checked November 2026.
The OAuth app
Apps requesting scopes Google classes as sensitive or restricted must pass verification. The sensitive scope guide wants a reason per scope, an unlisted demo video, a privacy policy on your domain and a verified domain, with review taking up to 10 days. Meanwhile an unverified app is capped at 100 new users.
Four Google quota regimes, then two more vendors
As of November 2026: GA4 charges tokens per property by request complexity, allows a standard property 10 concurrent requests, and returns 429 RESOURCE_EXHAUSTED when a bucket empties. Search Console's usage limits add 10-minute and daily load limits, hardest on page and query groupings. Google Ads sets access per Cloud project, and its Explorer level allows 2,880 operations a day on production accounts. Local Services reporting needs a manager account ID, and its detailed lead report is deprecated.
Yext and Local Falcon sit outside Google entirely. Each is its own vendor account, credentials and terms, with limits you would read in that vendor's documentation, so plan a third and fourth integration rather than a variation on the Google ones.
None of it is hard alone. Together it is a second product, due before your first chart.
Caching, retries and partial results in your own loop
DuckDive already stores history, so your cache only stops repeat work within a run. Keep it short-lived.
Before your loop goes on a schedule
- Key the cache tightly. Tool,
website_id,time_rangeand run date. - Refresh sparingly.
refresh_website_datais admin-only and runs once per website per 15 minutes. Never call it in a retry. - Retry 401 once. Refresh the access token and repeat the call. A second 401 means signed out: stop and alert.
- Treat 403 as scope or role. Retrying will not help.
- Back off on the rest. Exponential delay, jitter, a few attempts per site.
- Use nulls, not zeros. A missing source is unknown, not zero traffic.
DuckDive's connector guide says it logs the tool, website, time, success and a redacted request. Log the same on your side and support tickets get short.
Tokens, rate limits and revocation
Per the MCP spec: send Authorization: Bearer on every request, never put a token in a query string, keep refresh tokens confidential, and never assume one will be issued. Code the fallback: ask the owner to sign in again.
Rate limits are not published. Keep the pool small, stagger scheduled runs, and watch for 429s.
To revoke, POST the refresh token to the revocation endpoint. Under RFC 7009 that should also kill access tokens from the same grant, and a 200 comes back even for unknown tokens. Users can cut you off too, by disconnecting under AI Connectors.
Ask your agentWrite a small Node module that connects to https://api.duckdive.ai/mcp with the official MCP TypeScript SDK, runs the OAuth flow in my browser once, keeps the refresh token in the macOS keychain, and exposes callTool(name, args) with one retry on 401. Don't write any token to disk or to logs.
Tools it calls list_websites (as the smoke test)
Working in an existing agent instead? See DuckDive in Claude Code, DuckDive in Cursor, or what any MCP client needs.
When to build on Google's APIs instead
DuckDive is a narrow, stored read layer over six sources. Go direct when:
- You need exact dates. Calendar months and custom ranges are not available.
- You need more than 100 rows. A crawl-sized URL export belongs to the Search Console API, which pages through up to 25,000 rows per request.
- You need other GA4 dimensions. Device, country, events, audiences and revenue are not exposed. Neither are Search Console query-by-page splits.
- You need campaign detail. Google Ads comes through as an account summary, with no campaign, ad group or search-term rows.
- You need writes. DuckDive does not change Google settings or ads.
- You need other channels. Meta, CRM and ecommerce platforms are outside the six sources.
A common split: DuckDive for breadth across every site, one Google API call for the deep cut. Other servers are weighed in the marketing data MCP servers comparison.
Questions developers ask before writing the first call
Is there a REST API or an API key instead of MCP?
Not one that DuckDive documents. The supported interface is the MCP endpoint at https://api.duckdive.ai/mcp with an OAuth sign-in, and the agent guide says not to send an API key. Any language with an HTTP client and an OAuth library can call it, so you are not tied to an AI app.
Can my server-side job run without a person in the loop?
After one browser sign-in, yes in principle: the authorization server issues refresh tokens, so a job can trade the stored refresh token for fresh access tokens. Keep that refresh token in a secret store. How long one stays valid is not published yet, so build a path that alerts you to sign in again.
Can I serve dashboards to my own customers with my DuckDive token?
Treat that as unconfirmed. A token acts as the DuckDive user who signed in and sees every website that user can see. Showing that data to outside users is a product and terms question, so ask DuckDive before you build a customer-facing product on one seat.
Which tool arguments can I rely on?
Read them from tools/list at startup rather than from this page. As of November 2026, data tools take website_id and a fixed time_range enum, and the list tools take limit up to 100. Fail loudly in your client if a schema changes instead of sending arguments the server no longer accepts.
How do I get more than 100 rows or a custom date range?
You cannot through DuckDive today. Ranking tools stop at 100 rows, and the widest window the enum offers is last12months, with last7days the narrowest. For a full URL export or exact calendar months, call the Search Console or GA4 API directly for that one job.
What happens to my tool when a user disconnects?
Access stops immediately, per DuckDive's connector guide, and your next request gets a 401. Treat that as a signed-out state: stop the job, tell the owner, and do not retry in a loop. The same applies after your own code revokes a token.
Sources
- Set up DuckDive with your AI assistant, DuckDive AI; retrieved 16 Nov 2026.
- Streamable HTTP, Model Context Protocol specification (revision 2026-07-28); retrieved 16 Nov 2026.
- RFC 8414: OAuth 2.0 Authorization Server Metadata, IETF; retrieved 16 Nov 2026.
- RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol, IETF; retrieved 16 Nov 2026.
- RFC 7636: Proof Key for Code Exchange by OAuth Public Clients, IETF; retrieved 16 Nov 2026.
- MCP spec, Authorization chapter, 2026-07-28 revision; retrieved 16 Nov 2026.
- DuckDive for Claude, ChatGPT and other AI apps, the AI connectors guide from DuckDive AI; retrieved 16 Nov 2026.
- OAuth App Verification Help Center, Google Cloud Platform Console Help; retrieved 16 Nov 2026.
- Limits and quotas on API requests, GA4 Data API docs from Google; retrieved 16 Nov 2026.
- Access levels and permissible use, Google Ads API; retrieved 16 Nov 2026.
- Reporting, Local Services API, Google for Developers; retrieved 16 Nov 2026.
- Sensitive scope verification, Google Identity; retrieved 16 Nov 2026.
- Unverified apps, Google Cloud Platform Console Help; retrieved 16 Nov 2026.
- Usage limits, Search Console API; retrieved 16 Nov 2026.
- RFC 7009: OAuth 2.0 Token Revocation, IETF; retrieved 16 Nov 2026.
- Search Analytics: query, reference page in Google's Search Console API docs; retrieved 16 Nov 2026.
Last reviewed . The MCP specification and Google's API policies change often; recheck them before you ship. Gullwing Cycles, Meadowmint Tea, Tidewren Pottery and every number in EXAMPLE DATA blocks are fictional.
