AI assistant: any MCP client

Connect any MCP client to DuckDive with one URL and a Google sign-in

Your assistant, IDE, CLI or home-built agent is not Claude, ChatGPT or Cursor. Before you spend an afternoon on it, find out whether it can read your GA4 and Search Console data through DuckDive.

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

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.

Five things your client must handle to reach DuckDive
CheckWhat DuckDive expectsWhere to look in your client
1. Remote serversA hosted server reached by URL, nothing installedAn option to add a server by address, not only by command
2. Streamable HTTPThe standard HTTP transport for MCPA server type called HTTP or Streamable HTTP
3. OAuth that self-registersThe client registers itself, then signs inOAuth support for remote servers, with no client ID to type
4. Browser sign-inA person selects Continue with Google onceA browser that opens on the machine running the client
5. Tool callingThe model calls MCP tools while it answersTool 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.

Where DuckDive goes in each documented client
ClientHow to add DuckDiveWorth knowing
Claude (web, desktop, mobile)Pre-filled connector link, then Add and ConnectAny Claude plan, per DuckDive. Claude walkthrough
ChatGPTPlugins, +, Add custom MCP server, choose OAuthBusiness or Enterprise only. ChatGPT walkthrough
CursorDuckDive's install link, then ConnectCursor walkthrough
Claude Codeclaude mcp add --transport http duckdive https://api.duckdive.ai/mcp, then /mcpClaude Code walkthrough
VS CodeDuckDive's VS Code install link, then sign inProve it with a small task, then expand the tool call
GeminiSettings, Connected Apps, Add a custom app, paste the URLUS only, with a personal Google account
Grokgrok.com/connectors, New Connector, Custom, paste the URLName it DuckDive, select Add, then Connect
Gemini CLIgemini mcp add --transport http duckdive https://api.duckdive.ai/mcpThen /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.

  1. 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 http and the URL. If the only option asks for a command to run, jump to the bridge below.

  2. Paste the address and leave the rest blank

    Enter https://api.duckdive.ai/mcp exactly as written and name it duckdive. Leave headers, API key, client ID and client secret empty. If the form asks for an auth type, pick OAuth.

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

  4. Open a fresh session

    Many clients load tools when a session starts. Start one and switch DuckDive on in any per-chat tools menu.

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

client config (JSON)
{
  "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 agent
Which 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 agent
List my DuckDive websites and the data sources connected to each.

Tools it calls list_websites get_sync_status

Ask your agent
For 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:

EXAMPLE DATAFictional business: Harrowgate Cycles

Rung 1

Which DuckDive tools can you see right now? List them by name.

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

  1. list_websitestwo websites on the account, with their linked sources
  2. get_sync_statusHarrowgate Cycles, each source's state and latest day
  3. get_sync_statusHarrowgate Hire, same check

You have two websites. Everything linked is ready.

WebsiteLinked sourcesSync
Harrowgate CyclesGA4, Search Console, Google AdsReady, through Nov 15
Harrowgate HireGA4Ready, 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.

  1. get_ga4_overviewHarrowgate Cycles, last 7 days, sessions per day
  2. get_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.

DaySessionsSearch clicks
Mon Nov 9412141
Tue Nov 10398133
Wed Nov 11377128
Thu Nov 12405139
Fri Nov 13451152
Sat Nov 14523187
Sun Nov 15488171
Total3,0541,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.

Google Analytics 4 Search Console

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.

Continue with Google

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 agent
You 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

EXAMPLE DATAFictional business: Harrowgate Cycles

Morning run: latest day's sessions and search clicks for Harrowgate Cycles, with 7-day totals.

  1. list_websitesfirst run only; the website_id now lives in the agent's config
  2. get_sync_statusevery run, before any data call
  3. get_ga4_overviewlast 7 days; the agent posts the newest day and the total
  4. get_search_console_summarysame window, skipped when Search Console is not ready

Run log for four mornings:

RunSign-inPosted to chat
Wed Nov 11Access token validTue: 398 sessions, 133 clicks
Thu Nov 12Expired, renewed with refresh tokenWed: 377 sessions, 128 clicks
Fri Nov 13Refused, connection removed"DuckDive needs a fresh sign-in"
Mon Nov 16Valid after Friday's sign-inSun: 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.

Google Analytics 4 Search Console

Three habits keep a scheduled agent honest:

  • Call get_sync_status before 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.

What you see, the likely cause, and the fix
SymptomLikely causeFix
Error before any browser opensA header or key was added, or no OAuth supportRemove headers and keys; recheck point 3
No browser window ever appearsClient runs headless, over SSH or in a containerDo the first sign-in where a browser can open
DuckDive page says it expiredMore than 30 minutes passedStart connecting again from the client
Sign-in loops back to the startThat browser is not signed in to DuckDiveSign in to DuckDive there first, then reconnect
Connected, but no DuckDive toolsSession opened before sign-in, or DuckDive is offOpen a new session; switch DuckDive on
An action says not allowedActions unticked, or a team member accountReconnect with Also allow actions, or ask an admin
Website list comes back emptyThe account has no websites yetRun agent setup or add a site
A source returns blanks or zerosStill importing, or failingAsk for sync status; an admin can refresh
Worked yesterday, wants sign-in todayToken expired or connection removedSign 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 agent
Redo 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 agent
Check 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:

  1. Remove the server from the client so it stops calling DuckDive.
  2. Open AI Connectors in DuckDive and disconnect any entry you no longer use.
  3. 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.
  4. 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_report action 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

  1. Set up DuckDive with your AI assistant (agents.md), DuckDive, checked November 16, 2026.
  2. Overview (Transports), revision 2026-07-28, Model Context Protocol, checked November 16, 2026.
  3. Authorization, revision 2026-07-28, Model Context Protocol, checked November 16, 2026.
  4. DuckDive for Claude, ChatGPT and other AI apps (connector guide), DuckDive, checked November 16, 2026.
  5. MCP configuration reference, Visual Studio Code, checked November 16, 2026.
  6. MCP servers with Gemini CLI, Gemini CLI, checked November 16, 2026.
  7. Add and use MCP servers in VS Code, Visual Studio Code, checked November 16, 2026.
  8. mcp-remote README, GitHub, checked November 16, 2026.

Last reviewed . Numbers in EXAMPLE DATA blocks are fictional.

One URL, one sign-in, then ask

If your client passed the five checks, all that remains is a Google sign-in and three test questions.

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