Troubleshooting
Start with status:
npx -y @tagpilot/ga4-mcp status
It shows whether this computer is connected to Tag Pilot (with the first characters of its key) and signed in to Google. The server's own log goes to stderr (stdout is the MCP channel): in Claude Code, check /mcp or start claude --debug; other clients have an MCP log view.
Connecting
Not connected yet, or not sure?
Say "connect GA4" to get a link and code, or ask "is it connected?": the connection_status tool answers connected (with the device name), waiting (with the link and code again), not_connected or error with the next step. No terminal needed.
"Connect at … (code ABCD-1234), then ask again" Open the link in any browser, on any device (it doesn't have to be the computer that runs your AI client). Log in to Tag Pilot, check that the code matches, click Approve and sign in with Google, and allow Google Analytics access. Then ask again. The GA4 MCP keeps checking in the background, so you don't need to restart anything. The code is valid for 10 minutes; after that, ask again to get a new one.
The AI client times out during the first connect
A tool call waits 45 seconds, then answers with the link and code so the client doesn't give up. Connecting keeps going in the background: approve in the browser and repeat the question. If your client still times out, lower GA4_MCP_AUTH_WAIT_SECONDS, or connect from a terminal first:
npx -y @tagpilot/ga4-mcp login
login prints the link and code and waits until you approve. It works the same over SSH, in containers, in WSL and on remote dev boxes: open the link on whatever device has a browser.
"This code is unknown or has expired" (on the connect page) The code is older than 10 minutes or mistyped. Ask your AI client again for a fresh code.
"Connecting was not completed (denied)" or "(Google sign-in: access_denied)" You clicked Deny, or cancelled Google's consent screen. Ask again to start over, and allow See and download your Google Analytics data.
"The connect code expired" / "expired or was already used" Ask again to get a new code.
"This computer was disconnected from Tag Pilot" The device was revoked on the GA4 MCP page, so its saved connection was removed. Ask again to connect it again.
Google sign-in
"Google hasn't verified this app" Google is still reviewing Tag Pilot's app. Click Advanced, then Continue (or Go to … (unsafe)), to reach the consent screen.
"This app is blocked" or "Access blocked" Tag Pilot GA4 MCP is in a limited beta while Google's verification completes, and your Google account isn't allowed yet. Contact us through the Tag Pilot app with the Google account's email address, and we'll let you know when it's added.
Company Google account: "This app is blocked by your admin" or similar Google Workspace admins can block third-party apps. Ask your admin to trust Tag Pilot: in the Google Admin console, Security → Access and data control → API controls → Manage third-party app access, find the Tag Pilot app (or add it by its OAuth client ID, which we can send you) and set it to Trusted.
"Your Google sign-in for GA4 expired or was revoked" (Google invalid_grant)
Google no longer accepts the saved token, so it was deleted. Ask again and approve again. Google expires tokens after 6 months without use and when you remove the app's access in your Google account, and may also expire them after a password change.
With an API key (CI and headless)
These only apply when TAGPILOT_API_KEY is set. Without it, the GA4 MCP connects through the browser instead.
"Tag Pilot rejected TAGPILOT_API_KEY (invalid or revoked)" (HTTP 401) The key is mistyped, incomplete or revoked. Create a new key on the GA4 MCP page under Create a key manually, or remove the variable to connect through the browser.
"TAGPILOT_API_KEY does not have the ga4:mcp scope" (HTTP 403) The key was made elsewhere in the app, for example a Lead Tracking or Search Console MCP key. Create a key on the GA4 MCP page instead.
"Finish signing in with Google at …, then ask again"
With a key, only Google's sign-in is needed. Open the link in any browser, approve, then ask again. From a terminal: TAGPILOT_API_KEY=tpk_your_key npx -y @tagpilot/ga4-mcp login.
Tag Pilot API errors
| Message | Meaning | What to do |
|---|---|---|
| "Tag Pilot rate limit reached" (429) | Too many connect, sign-in or token requests in a short time | Wait for the time in the message |
| "Tag Pilot could not reach Google to exchange the sign-in token" (502) | Google's token service didn't answer | Usually temporary; try again shortly |
| "Google sign-in for the GA4 MCP is not available" (503) | Sign-in is switched off on Tag Pilot's side | Try again later; contact us if it persists |
| "Could not reach Tag Pilot" | No connection to api.tagpilot.io |
Check your internet connection, proxy or firewall |
Only connecting, sign-in and token refreshes go through Tag Pilot (about once an hour while you use it). Reports keep working as long as the current access token is valid.
Google Analytics errors
"The signed-in Google account has no access to property …"
That Google account needs at least the Viewer role on the GA4 property. Ask "Which GA4 properties do I have?" to see what it can read. Signed in with the wrong account? Run npx -y @tagpilot/ga4-mcp logout and ask again.
"… is not a GA4 property ID" / "Not found"
Use the numeric property ID (e.g. 123456789), not the measurement ID (G-XXXXXXX). Universal Analytics properties (UA-…) aren't supported.
"GA4 rejected the request"
A dimension or metric name is wrong, or the two can't be combined (for example some item-scoped and session-scoped fields). Custom fields need their API name, such as customEvent:payment_type; ask the AI client to look them up with get_custom_dimensions_and_metrics.
"GA4 quota exhausted" (429)
GA4 Data API quotas are per property and refill hourly and daily. They're shared with other tools reading the same property (Looker Studio, other apps). Wait a few minutes, or make requests cheaper: shorter date ranges, fewer dimensions, lower row limits. Ask for return_property_quota: true to see what's left. Limits are in Google's quota documentation.
"Google Analytics API error (HTTP 5xx)" A problem on Google's side; retry shortly. Funnel reports use Google's alpha funnel API, which fails more often than other reports.
Numbers differ from the GA4 interface
The tools return what Google's Data API returns, with notes when it adjusts the data:
- Thresholding: with Google signals or demographics, GA4 can hide rows with few users, so totals can be lower. Removing demographic dimensions or widening the date range helps.
- Sampling: the result says how many events it was based on.
(other)rows: with many distinct values, GA4 groups the rest into(other). Narrow the date range or add filters.- Different settings: check the date range, the time zone (reports use the property's), the attribution scope (session vs first-user dimensions) and whether the GA4 report has filters or comparisons applied.
- Recent data: the last 24–48 hours can still change while GA4 processes them.
MCP client issues
The tools don't show up
MCP servers load when your AI client's session starts, so a server added during a session isn't there yet. Start a new session or reconnect: in Claude Code, run /mcp (or start a new claude session); in Claude Desktop, Cursor and VS Code, restart the app or reload the window. Still missing? Check the server's log, and make sure Node.js 18 or newer is installed: node --version (not needed for the Claude Desktop extension).
It keeps running an old version
npx caches packages, so it can keep starting an older version. Ask for the latest explicitly by using npx -y @tagpilot/ga4-mcp@latest (in your client's args too), or clear the cache by deleting ~/.npm/_npx and restart the client. npx -y @tagpilot/ga4-mcp --version shows which version runs.
"npx: command not found" or "spawn npx ENOENT"
Desktop apps don't always see the PATH from your shell (common with nvm or Homebrew). Use the full path to npx as the command, from which npx (macOS, Linux) or where npx (Windows).
Still stuck? Contact us through the Tag Pilot app and include the status output (it shows only the first characters of the device's key).