The short answer
A client works with DuckDive if it can add a remote server by URL, speak Streamable HTTP, run an OAuth sign-in that registers itself, open a browser once, and let its model call tools. Add https://api.duckdive.ai/mcp, leave keys and headers blank, continue with Google, then ask it to name the DuckDive tools it sees.
- Read your client's docs against the five checks before installing anything.
- A client limited to local programs can still try a community bridge.
- Three test questions, asked in order, show which layer broke.
Will your client work? A five-point check
At the other end of the URL, DuckDive pairs every website you own with the right GA4 property, Search Console property and ad accounts (plus Yext and Local Falcon where used), imports their history and keeps it. The Google work happens once, on DuckDive's side. Your client only has to reach one address and finish one sign-in. Five checks decide whether it can.
| Check | What DuckDive expects | Where to look in your client |
|---|---|---|
| 1. Remote servers | A hosted server reached by URL, nothing installed | An option to add a server by address, not only by command |
| 2. Streamable HTTP | The standard HTTP transport for MCP | A server type called HTTP or Streamable HTTP |
| 3. OAuth that self-registers | The client registers itself, then signs in | OAuth support for remote servers, with no client ID to type |
| 4. Browser sign-in | A person selects Continue with Google once | A browser that opens on the machine running the client |
| 5. Tool calling | The model calls MCP tools while it answers | Tool use switched on for the model you picked |
Sources: DuckDive agent setup guide and DuckDive's published OAuth metadata, checked November 2026.
Remote servers. Plenty of clients started local-only: you hand them a command and they launch a program on your laptop. DuckDive is not a program you run, so your client must accept a web address.
Streamable HTTP. The MCP transports overview names two standard transports as of November 2026: stdio for programs the client launches, and Streamable HTTP for servers at a URL. DuckDive uses the second. If your client's only web option is SSE, use the bridge below, which speaks Streamable HTTP to DuckDive.
OAuth that self-registers. The MCP authorization specification gives HTTP servers an OAuth flow and tells stdio servers to read credentials from the environment. DuckDive answers an unsigned request with a 401 pointing to its sign-in metadata; a capable client follows it, registers itself and opens the sign-in page. The 2026-07-28 spec prefers a newer method, Client ID Metadata Documents, and still allows dynamic registration so older clients keep working. DuckDive advertises dynamic registration, so make sure your client still does it.
Browser sign-in. There is no key to paste; DuckDive's guide tells clients not to send an Authorization header. A person clicks Continue with Google in a real browser at least once.
Tool calling. DuckDive works entirely through tools, 22 of them as of November 16, 2026. A client that only reads MCP resources, or a model with tool use off, connects cleanly and never fetches a number.
Shortcut
Docs vague on point 3? Add the server anyway. A DuckDive sign-in page opening means checks 1 to 4 all pass.
Clients with documented setup steps
DuckDive's guides give exact steps for these eight clients; four have a full walkthrough here, and the rest are summarised from DuckDive's connector guide and each client's docs as of November 2026. Known routes, not a whitelist.
| Client | How to add DuckDive | Worth knowing |
|---|---|---|
| Claude (web, desktop, mobile) | Pre-filled connector link, then Add and Connect | Any Claude plan, per DuckDive. Claude walkthrough |
| ChatGPT | Plugins, +, Add custom MCP server, choose OAuth | Business or Enterprise only. ChatGPT walkthrough |
| Cursor | DuckDive's install link, then Connect | Cursor walkthrough |
| Claude Code | claude mcp add --transport http duckdive https://api.duckdive.ai/mcp, then /mcp | Claude Code walkthrough |
| VS Code | DuckDive's VS Code install link, then sign in | Prove it with a small task, then expand the tool call |
| Gemini | Settings, Connected Apps, Add a custom app, paste the URL | US only, with a personal Google account |
| Grok | grok.com/connectors, New Connector, Custom, paste the URL | Name it DuckDive, select Add, then Connect |
| Gemini CLI | gemini mcp add --transport http duckdive https://api.duckdive.ai/mcp | Then /mcp auth duckdive; needs a local browser |
Sources: DuckDive connector guide, VS Code MCP configuration reference and Gemini CLI MCP documentation, checked November 2026.
Two details from the clients' own docs. VS Code's guide to adding MCP servers suggests proving a new server with a small task, then expanding the tool call in the chat; Disable and Uninstall sit in the server's ellipsis menu. Gemini CLI's OAuth flow needs a local browser and a localhost redirect, so it fails headless, over SSH without X11 forwarding, and in browserless containers. Its tokens live in ~/.gemini/mcp-oauth-tokens.json, and gemini mcp remove duckdive deletes the entry.
These apps rename their menus now and then. When a label has moved, DuckDive's guide says to look for Connectors, Apps or MCP.
Connecting a client that is not on the list
DuckDive's agent guide covers every other client in one line: add a custom connector with the MCP URL and sign in when asked. That line hides five small decisions.
-
Find the screen that takes a server URL
Look in settings for Connectors, MCP, Tools, Integrations or Custom apps. Some clients use a JSON config file instead; there the entry needs a name, a type of
httpand the URL. If the only option asks for a command to run, jump to the bridge below. -
Paste the address and leave the rest blank
Enter
https://api.duckdive.ai/mcpexactly as written and name itduckdive. Leave headers, API key, client ID and client secret empty. If the form asks for an auth type, pick OAuth. -
Sign in and decide what the client may change
Saving should open a DuckDive page. Select Continue with Google; with no DuckDive account yet, that click creates one. If DuckDive recognises you, it skips Google and shows an approval page instead. For a client that should only read, clear the Also allow actions box; leave it ticked if this client should add sites, link sources, refresh data or schedule reports. Then Allow. The page times out after 30 minutes.
-
Open a fresh session
Many clients load tools when a session starts. Start one and switch DuckDive on in any per-chat tools menu.
-
Climb the test ladder
Three questions, in the next section, in order.
If your client only launches local servers
Some desktop apps and older editor plugins can only start a program over stdio. A community bridge, mcp-remote, fills the gap: your client launches it locally, and it connects to the remote server and runs the OAuth sign-in. Its README says it registers dynamically when a server advertises nothing else, keeps credentials in ~/.mcp-auth, and tries HTTP before SSE by default (as of November 2026). It needs Node.js.
{
"mcpServers": {
"duckdive": {
"command": "npx",
"args": ["mcp-remote", "https://api.duckdive.ai/mcp"]
}
}
}
DuckDive did not build mcp-remote and does not document it, so run the test ladder before relying on it.
If you wrote the client yourself
If your agent framework or MCP SDK has an OAuth helper for remote servers, use it. Your part is the browser hop on the first run and a safe home for the tokens afterwards. DuckDive issues refresh tokens, so a stored one lets the agent carry on alone, but the spec tells clients never to count on one, so build a path that asks a human to sign in again. Endpoints, scopes and revocation are in the protocol reference for developers.
Worked example: the first three questions to test a connection
Harrowgate Cycles is a fictional bike shop with two websites in DuckDive: the shop and a bike hire site. Its owner has just added DuckDive to a terminal assistant that appears on nobody's list. Three prompts form a test ladder. Rung one proves the transport, the sign-in and that the client hands the tool list to its model, without reading any data. Rung two proves the token belongs to the DuckDive account you meant. Rung three proves the client can pass arguments and get real figures back.
Ask your agentWhich DuckDive tools can you see right now? List them by name.
Tools it calls tools/list (read by the client when the session opens)
Ask your agentList my DuckDive websites and the data sources connected to each.
Tools it calls list_websites get_sync_status
Ask your agentFor Harrowgate Cycles, give me the last 7 days of sessions and Search Console clicks.
Tools it calls get_ga4_overview get_search_console_summary
Swap in your own site's name. Here is the whole run in the owner's terminal:
Rung 1
Which DuckDive tools can you see right now? List them by name.
tools/listsent by the client when the session opened; a protocol request, not a DuckDive data tool
I can see 22 DuckDive tools.
Finding sites: list_websites, get_website, search, fetch.
Setup and status: get_setup_status, list_available_sources, get_sync_status.
Data: get_ga4_overview, get_ga4_channels, get_ga4_landing_pages, get_search_console_summary, get_search_console_keywords, get_search_console_pages, get_google_ads_summary, get_lsa_summary, get_yext_summary, get_yext_reviews, get_local_rankings.
Actions: add_website, connect_website_sources, refresh_website_data, create_scheduled_report.
Rung 2
List my DuckDive websites and the data sources connected to each.
list_websitestwo websites on the account, with their linked sourcesget_sync_statusHarrowgate Cycles, each source's state and latest dayget_sync_statusHarrowgate Hire, same check
You have two websites. Everything linked is ready.
| Website | Linked sources | Sync |
|---|---|---|
| Harrowgate Cycles | GA4, Search Console, Google Ads | Ready, through Nov 15 |
| Harrowgate Hire | GA4 | Ready, through Nov 15 |
Harrowgate Hire has no Search Console site, so search questions about it will come back empty.
Rung 3
For Harrowgate Cycles, give me the last 7 days of sessions and Search Console clicks.
get_ga4_overviewHarrowgate Cycles, last 7 days, sessions per dayget_search_console_summarysame site and window, clicks per day
November 9 to 15: 3,054 sessions and 1,051 Search Console clicks. Saturday was the busiest day on both.
| Day | Sessions | Search clicks |
|---|---|---|
| Mon Nov 9 | 412 | 141 |
| Tue Nov 10 | 398 | 133 |
| Wed Nov 11 | 377 | 128 |
| Thu Nov 12 | 405 | 139 |
| Fri Nov 13 | 451 | 152 |
| Sat Nov 14 | 523 | 187 |
| Sun Nov 15 | 488 | 171 |
| Total | 3,054 | 1,051 |
The columns count different things: a click starts on a Google results page, a session is any visit GA4 recorded. Expect clicks well below sessions.
Read a failure by its rung. Rung one fails: back to the five checks. Rung two finds no websites: the connection works and the account is empty, so let your agent set DuckDive up. Rung three shows numbers but no tool call: see the troubleshooting note on guessed answers.
Climb the same three rungs on your own account
Sign up free, add the URL to your client, and your own websites show up in the second answer.
Free for 2 sites · No credit card
Worked example: an in-house agent that runs on a schedule
Harrowgate's owner also runs a small home-built agent on the shop's office server. At 06:30 each weekday it posts two lines to the team chat. Nobody watches it run, so the numbers are the easy part; what matters is how it behaves when sign-in or data is not ready.
The first run needed a person: the owner started it from a laptop, selected Continue with Google, and the framework saved the refresh token in the server's secret store. Since then it runs alone on this instruction:
Ask your agentYou run unattended at 06:30 on weekdays. Check DuckDive sync status for Harrowgate Cycles first. Post the latest day's sessions and Search Console clicks, plus the 7-day totals. If a source is importing or failing, name it and leave its number out; never print a zero you did not read. If DuckDive refuses the sign-in, post "DuckDive needs a fresh sign-in" and stop.
Tools it calls get_sync_status get_ga4_overview get_search_console_summary
Morning run: latest day's sessions and search clicks for Harrowgate Cycles, with 7-day totals.
list_websitesfirst run only; the website_id now lives in the agent's configget_sync_statusevery run, before any data callget_ga4_overviewlast 7 days; the agent posts the newest day and the totalget_search_console_summarysame window, skipped when Search Console is not ready
Run log for four mornings:
| Run | Sign-in | Posted to chat |
|---|---|---|
| Wed Nov 11 | Access token valid | Tue: 398 sessions, 133 clicks |
| Thu Nov 12 | Expired, renewed with refresh token | Wed: 377 sessions, 128 clicks |
| Fri Nov 13 | Refused, connection removed | "DuckDive needs a fresh sign-in" |
| Mon Nov 16 | Valid after Friday's sign-in | Sun: 488 sessions, 3,054 for 7 days; clicks held, Search Console importing |
Friday's run made no data calls. Someone tidying the AI Connectors page on Thursday evening had removed the agent's connection, so DuckDive refused it and the agent posted one line instead of an empty report. The owner signed in again at 09:10. Separately, a Search Console refresh the owner queued late on Sunday left that source mid-import on Monday morning; the agent said so instead of posting a low click count. The import finished by mid-morning, before the terminal test above.
Three habits keep a scheduled agent honest:
- Call
get_sync_statusbefore any data tool, and write "importing" where a number would be. - Treat a refused sign-in as a stop, not a retry loop. Post once, then exit.
- Before deleting entries on the AI Connectors page, check which belongs to an unattended agent.
DuckDive has not published how long a refresh token lasts, so plan for an occasional fresh sign-in anyway.
Troubleshooting by symptom
Fixes tied to one app live on that app's page. These symptoms look the same in every client, so start here.
| Symptom | Likely cause | Fix |
|---|---|---|
| Error before any browser opens | A header or key was added, or no OAuth support | Remove headers and keys; recheck point 3 |
| No browser window ever appears | Client runs headless, over SSH or in a container | Do the first sign-in where a browser can open |
| DuckDive page says it expired | More than 30 minutes passed | Start connecting again from the client |
| Sign-in loops back to the start | That browser is not signed in to DuckDive | Sign in to DuckDive there first, then reconnect |
| Connected, but no DuckDive tools | Session opened before sign-in, or DuckDive is off | Open a new session; switch DuckDive on |
| An action says not allowed | Actions unticked, or a team member account | Reconnect with Also allow actions, or ask an admin |
| Website list comes back empty | The account has no websites yet | Run agent setup or add a site |
| A source returns blanks or zeros | Still importing, or failing | Ask for sync status; an admin can refresh |
| Worked yesterday, wants sign-in today | Token expired or connection removed | Sign in again; check AI Connectors |
Causes and fixes drawn from the agent setup guide and the connector guide DuckDive publishes, as checked in November 2026.
Numbers with no tool call behind them
Sometimes an answer arrives fluent and specific while the client shows no DuckDive call. The model guessed, usually because tools were off for that chat. Make it show its work:
Ask your agentRedo that answer using DuckDive tools only. Before any number, list each tool you called with its website_id and time_range. If you can't call a tool, say so instead of estimating.
Tools it calls list_websites get_ga4_overview
For a routine, see how to check your AI agent's marketing numbers.
A source that looks empty, stale or off
A newly linked source takes a while to import. Ask before you assume a drop:
Ask your agentCheck DuckDive sync status for every source on Harrowgate Hire. Which are importing, which are failing, and what's the latest day each one has?
Tools it calls list_websites get_sync_status
If a source is stuck, an admin's client can call refresh_website_data to re-fetch as many as 30 recent days; DuckDive accepts one such request per site per quarter hour. If a figure disagrees with the GA4 screen, compare windows first: DuckDive uses fixed ranges, never calendar dates. Metric definitions are on the GA4 source page.
Disconnecting a client
DuckDive's connector guide names two switches, and either ends access immediately: the AI Connectors page in DuckDive, or removing the server from the client. Retiring a client for good takes four steps:
- Remove the server from the client so it stops calling DuckDive.
- Open AI Connectors in DuckDive and disconnect any entry you no longer use.
- For an in-house agent, delete the stored refresh token from its secret store. If your code can call DuckDive's revocation endpoint, do that first.
- Ask the old client the rung one question. It should no longer list any DuckDive tools.
Disconnecting ends that client's access at once. DuckDive's connector guide says a connector can't delete data, and reconnecting later means the same five steps and a fresh sign-in.
When a direct connection is the wrong plan
- Nobody can ever open a browser for it. Every connection begins with a person selecting Continue with Google.
- Your client wants a client ID issued in advance. DuckDive advertises a registration endpoint, not client IDs to paste.
- The bot answers a shared channel. Its token carries the identity of whoever signed in, so the bot can read every site in that person's account. If the channel should see less, sign the bot in with an account whose access fits that audience.
- You only want a recurring summary. DuckDive's
create_scheduled_reportaction emails one daily, weekly or monthly to your own account address, with no client to maintain. Admins only. - You need data DuckDive does not hold. It reads six sources, in fixed windows, at most 100 rows per call. Servers that cover other sources are lined up in the marketing data MCP servers comparison.
Questions about other clients
My client is not on any list. Is it worth trying?
Yes, if it passes the five checks. The documented clients are the ones DuckDive has written steps for, not the only ones that can connect. Adding the URL and asking the first test question settles it, and the free plan covers one website with no credit card.
My client only accepts a bearer token or a custom header. Can it still connect?
Not directly. There is no DuckDive token you can copy into a header field, because each token comes out of a browser sign-in. Put the mcp-remote bridge in front of the client so the bridge handles sign-in and token renewal, or, if the client cannot launch a local program either, use one of the alternatives under When a direct connection is the wrong plan.
How long does a sign-in last before my client asks again?
DuckDive's authorization server issues refresh tokens, so a client that stores one can renew its access without bothering you. DuckDive has not published how long that lasts. Expect to sign in again now and then, and give any unattended agent a way to ask a person when that happens.
Do I need to be a DuckDive admin to connect a client?
Not to read. Any DuckDive login can connect and ask about the websites it can see. The four actions (add a website, link sources, refresh data, schedule a report) need an Agency Admin or Client Admin account and Also allow actions ticked at sign-in.
Does my client need to support MCP resources or prompts?
No. Everything DuckDive does happens through its 22 tools (as of November 16, 2026), and it publishes no resources for a client to browse. A client with tools and nothing else gets the full product; a client with resources and no tool calling gets nothing useful. When a feature table lists Tools, Resources and Prompts, the Tools column is the only one that decides it.
Sources
- Set up DuckDive with your AI assistant (agents.md), DuckDive, checked November 16, 2026.
- Overview (Transports), revision 2026-07-28, Model Context Protocol, checked November 16, 2026.
- Authorization, revision 2026-07-28, Model Context Protocol, checked November 16, 2026.
- DuckDive for Claude, ChatGPT and other AI apps (connector guide), DuckDive, checked November 16, 2026.
- MCP configuration reference, Visual Studio Code, checked November 16, 2026.
- MCP servers with Gemini CLI, Gemini CLI, checked November 16, 2026.
- Add and use MCP servers in VS Code, Visual Studio Code, checked November 16, 2026.
- mcp-remote README, GitHub, checked November 16, 2026.
Last reviewed . Numbers in EXAMPLE DATA blocks are fictional.
