For developers

Build your own marketing reporting tool on DuckDive's remote MCP server

You need GA4, Search Console, Ads, LSA, Yext and Local Falcon numbers inside your own tool, and you would rather not register a Google OAuth app, juggle four Google quota systems plus two more vendor APIs, or build a history store first. Here is the contract you would code against.

Continue with Google

Free for 2 sites · No credit card

Or have your agent set it up

Set up DuckDive for my website. Follow https://analytics.duckdive.ai/agents.md

Updated 16 min read

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:read scope; setup and refresh calls need mcp:actions plus 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_token and a resource_metadata URL in the WWW-Authenticate header.
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:read and mcp: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.

What an unauthenticated POST gets back
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.

  1. Follow the 401 to the metadata

    The resource_metadata URL names the authorization server. Its RFC 8414 metadata document lists the authorization, token, registration and revocation endpoints. Read them; do not hard-code them.

  2. Register your client once

    POST your client_name, redirect_uris and grant_types to the registration endpoint, as RFC 7591 describes, and keep the returned client_id, keyed by issuer.

  3. 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 resource set to the MCP endpoint. The user selects Continue with Google (or Allow, if already signed in) and decides whether Also allow actions stays ticked.

  4. 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.

  5. List the tools before calling any

    Validate arguments against the schemas tools/list returns, then call list_websites as 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 agent
Call 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.

Which scope a feature in your tool needs
What your code callsmcp:readmcp:actions
Six sources' data toolsYes, the whole reporting surfaceNot needed
list_websites, get_website, search, fetchYesNot needed
get_sync_status, get_setup_statusYes, read-only statusNot needed
refresh_website_dataNoYes, admin seat only
add_website, connect_website_sourcesNoYes, admin seat only
create_scheduled_reportNoYes, 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.

Inputs and limits for the tools a reporting tool calls most
ToolInputsLimits
list_websitessearch, limit, offsetDefault 50, maximum 100 per page
get_websitewebsite_idOne site's name, URL and linked sources
get_search_console_summarywebsite_id, time_rangeClicks, impressions, CTR, position over time
get_ga4_landing_pageswebsite_id, time_range, limitDefault 25, maximum 100 rows
get_sync_statuswebsite_idPer source: ready, importing or failing, and recency
refresh_website_datawebsite_id, source, days1 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 agent
Which 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 agent
Generate 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:

  1. Page the roster. list_websites with limit 100, stepping offset until a page comes back short.
  2. Gate on freshness. get_sync_status per site; flag sources that are importing or failing.
  3. Bound concurrency. A small worker pool; rate limits are not published, so start low.
  4. Collect errors per site. One failure lands in an array, not an aborted run.
  5. Merge last, label the window. Every output row carries the time_range it came from.
fanout.ts, the shape of the loop (parse helpers left to your real responses)
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 agent
List 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.

EXAMPLE DATAFictional business: Gullwing Cycles, Meadowmint Tea and Tidewren Pottery

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.

  1. list_websitesone page, three sites
  2. get_sync_statuseach site; Tidewren's GA4 still importing
  3. get_search_console_summaryeach site, last 7 days
  4. get_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.

digest-2026-11-16.json
{
  "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.

Search Console Google Analytics 4

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.

Continue with Google

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.

EXAMPLE DATAFictional business: Meadowmint Tea

@sitebot how is meadowmint doing?

  1. list_websitessearch "meadowmint", one match
  2. get_sync_statusGA4 and Search Console ready
  3. get_ga4_overviewlast 30 days
  4. get_search_console_summarylast 30 days
  5. get_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 pageSessionsConversionsConv. rate
/collections/matcha1,980180.9%
/blog/cold-brew-ratios1,64080.5%
/products/sampler-tin1,210473.9%

Want last 7 days, or the search queries behind these pages?

Google Analytics 4 Search Console

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.

What you build and run, by route
JobOn DuckDiveGoogle's APIs directly
Google sign-in for other peopleDone, DuckDive's sign-inYours, your OAuth app and its review
What a question costs at GoogleNot a live call, reads stored dataPer property, 429 when a bucket empties
Google Ads accessYes, account-level summaryAccess level per Cloud project
Local Services AdsYes, leads, charged leads, spendPartly, needs a manager account
Yext and Local FalconSame pattern, per websiteTwo more vendors, two more auth flows
History storeKept per websiteYours, tables, backfills, schedulers
Depth on one propertyPartly, fixed ranges, 100 rowsBetter, 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_range and run date.
  • Refresh sparingly. refresh_website_data is 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 agent
Write 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

  1. Set up DuckDive with your AI assistant, DuckDive AI; retrieved 16 Nov 2026.
  2. Streamable HTTP, Model Context Protocol specification (revision 2026-07-28); retrieved 16 Nov 2026.
  3. RFC 8414: OAuth 2.0 Authorization Server Metadata, IETF; retrieved 16 Nov 2026.
  4. RFC 7591: OAuth 2.0 Dynamic Client Registration Protocol, IETF; retrieved 16 Nov 2026.
  5. RFC 7636: Proof Key for Code Exchange by OAuth Public Clients, IETF; retrieved 16 Nov 2026.
  6. MCP spec, Authorization chapter, 2026-07-28 revision; retrieved 16 Nov 2026.
  7. DuckDive for Claude, ChatGPT and other AI apps, the AI connectors guide from DuckDive AI; retrieved 16 Nov 2026.
  8. OAuth App Verification Help Center, Google Cloud Platform Console Help; retrieved 16 Nov 2026.
  9. Limits and quotas on API requests, GA4 Data API docs from Google; retrieved 16 Nov 2026.
  10. Access levels and permissible use, Google Ads API; retrieved 16 Nov 2026.
  11. Reporting, Local Services API, Google for Developers; retrieved 16 Nov 2026.
  12. Sensitive scope verification, Google Identity; retrieved 16 Nov 2026.
  13. Unverified apps, Google Cloud Platform Console Help; retrieved 16 Nov 2026.
  14. Usage limits, Search Console API; retrieved 16 Nov 2026.
  15. RFC 7009: OAuth 2.0 Token Revocation, IETF; retrieved 16 Nov 2026.
  16. 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.

Skip the OAuth app, call one endpoint

Sign in with Google, link a site, and your code can read its six sources through one MCP server today.

Free for 2 sites · No credit card · Working in an agent? Let it set DuckDive up