analytics_ops 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f71655d305efa516ee61d1d1059078f6e0bd562949a542e764dceff69eb58017
-  data.tar.gz: d73a4e6cb8aa1de4ec019104bcc28ab259be236dd41612f73be4124a0f4bae56
+  metadata.gz: a081c51447259f1fd4755d6758cadc76878668a5851e96408e286c64885fdcb7
+  data.tar.gz: 6e5724c104b4946735b9967d1de1a10e70892828901d7eb7dd0190023af2ee92
 SHA512:
-  metadata.gz: ff58c5f35e8573755d4dab309163602124fda905aa2e452568e04ceef4d12d8b370e2d573b7783ab150b6083c2657dbf9cf03e6c4124ca8931cfe4ef01966679
-  data.tar.gz: 5495494e5cae8ba1a786644752038a5749cf4aa2cdb05cbfc12da0923c8558596be1391b3f1806cf7739ea6ad13ea57a01150ff0e69e2f4e57a86232ab14df86
+  metadata.gz: 8d422c66448843f84a387fdd39526d7fe9e6545f16760fcedaa840250a8356e3f6612be151cd115ee0120b1074b406d39d115546ce460571039c8653b2cdd59d
+  data.tar.gz: 0c42714dbfc96aa557344f8930d55e4a1087bce24eb2f3d22db3d904fc83ce8c3803ad122daae2a6a45ffeb8aa5e7d6b304c4e3e3c882192ebe77e6851671339

data/CHANGELOG.md

@@ -3,6 +3,114 @@
 Analytics Ops follows Semantic Versioning for its public Ruby, CLI,
 configuration, and plan contracts.
 
+## [Unreleased]
+
+## [0.3.0] - 2026-07-23
+
+### Added
+
+- Named service-account connections with per-configuration profile mappings,
+  `connections`, `profiles`, and `use` commands, plus automatic migration from
+  the version-1 single-key pointer.
+- Collision-safe automatic connection names when separate applications both
+  use the default `production` profile with different credentials.
+- Safe additive setup for a second property profile without hand-editing YAML.
+- `--last`, `--from`, `--to`, and `--compare` for standard reports and
+  overviews, with bounded equal preceding-period comparisons.
+- A read-only `portfolio` summary across every configured property and its
+  associated Google connection.
+- A local stdio `mcp` server for ChatGPT desktop, Codex, and Claude Code. Its
+  strict tool allowlist covers the read-only capabilities described below and
+  contains no mutation operation.
+- Service-account file permission and Git-repository placement warnings in
+  setup and doctor.
+- A beginner-friendly AI connection guide with the exact local commands,
+  privacy boundary, and optional OpenAI Secure MCP Tunnel explanation.
+- Property-aware report field discovery and compatibility checks, saved YAML
+  recipes, bounded one-off custom reports, recursive boolean/list/null/numeric
+  filters, and atomic streaming CSV exports up to an explicit hard limit.
+- Deterministic `health` checks for traffic and key-event drops, expected
+  events, acquisition quality, Google thresholding/sampling, quota, and
+  configuration drift.
+- Generalized portfolio reports and health across all profiles with bounded
+  concurrency, profile labels, stable ordering, and isolated per-property
+  failures.
+- Experimental read-only governance snapshots and policy checks for Enhanced
+  Measurement, stream redaction, reporting identity, attribution, channel
+  groups, calculated metrics, event rules, and BigQuery links.
+- Experimental bounded, de-identified change history and portable aggregate
+  Data API quota-access reporting.
+- Optional fixed GA4 BigQuery Export recipes and aggregate ordered funnels
+  using the official client, a mandatory dry run and byte cap, parameterized
+  SQL, and bounded normalized results.
+- Expanded the local MCP allowlist to 21 strictly read-only tools, including
+  field discovery, compatible custom reports, health, generalized portfolio,
+  governance, and optional cost-capped BigQuery/funnel reads.
+- New Rails tasks and dedicated health, governance, and BigQuery/funnel
+  operator guides.
+
+### Changed
+
+- Verify future RubyGems releases from the published artifact instead of
+  waiting for the legacy full index, which can lag behind a successful
+  Trusted Publishing upload.
+- Rails generator and CLI setup now share the `production` default. Setup can
+  fill the untouched generated placeholder, and Rails tasks use the locally
+  selected profile unless `ANALYTICS_OPS_PROFILE` explicitly overrides it.
+- The mode-`0600` user connection file now stores multiple named key paths and
+  profile selections while still storing no key material.
+- Google transport errors preserve bounded structured reason, metadata, and
+  status values so disabled-API guidance does not depend on English wording.
+- Saved and direct custom reports validate live property metadata and Google's
+  compatibility result before running.
+- Portfolio human and CSV output now includes property identity and optional
+  local labels.
+
+### Fixed
+
+- Declare CSV as an explicit runtime dependency for Ruby 3.4 and newer, where
+  it is no longer bundled as a default gem.
+- Show complete redacted before/after values during interactive apply instead
+  of truncating the exact operation being approved.
+- Require `--non-interactive --yes` for JSON apply so prompts can never corrupt
+  machine-readable standard output.
+- Reject duplicate stream IDs during configuration loading instead of failing
+  later during planning.
+- Preserve both the beginning and ending of long human report cells so similar
+  URLs remain visibly distinct.
+- Validate saved connection mappings against existing connection names.
+- Use each web stream—not the property root—for event create/edit rule reads,
+  and supply the required parent account when requesting change history.
+- Use non-360 aggregate Data Access fields so the default access query works
+  on ordinary GA4 properties.
+- Preserve a report definition's starting offset during paginated export.
+- Avoid false health findings when a configured percentage threshold is zero.
+- Reject malformed public BigQuery results and irrelevant null-filter options.
+- Validate configured realtime fields without sending them through the
+  standard-only compatibility endpoint.
+- Reject date flags on compatibility checks instead of accepting options the
+  Google compatibility request cannot use.
+- Refuse partial portfolio CSV output and reject BigQuery results whose actual
+  processed bytes exceed the configured cap.
+- Reject oversized Data API cells and responses that exceed the requested row
+  limit so malformed remote output cannot bypass a bounded report or export.
+- Reject compatibility responses that omit, duplicate, or substitute requested
+  fields instead of treating an incomplete Google response as compatible.
+
+### Security
+
+- Every MCP tool is explicitly annotated read-only and non-destructive; the
+  server contains no plan, apply, create, update, delete, archive, credential,
+  or key-path tool.
+- Starting MCP, listing local profiles, and switching profiles perform no
+  Google network access or credential loading.
+- MCP input schemas are strict and bounded, tool errors are redacted, and
+  unexpected exceptions do not expose internal details.
+- Change-history output omits actor email and full before/after resources.
+- Optional BigQuery support has no arbitrary-SQL entry point, uses only the
+  read-only OAuth scope, never returns funnel user identifiers, and applies
+  the configured billing cap to both dry-run and real query jobs.
+
 ## [0.2.0] - 2026-07-22
 
 ### Added

data/CONTRIBUTING.md

@@ -32,6 +32,7 @@ mounted read-only except for source edits.
 - Do not introduce telemetry, a database, browser analytics, or boot-time
   network access.
 - Preserve the read-only default and saved-plan confirmation boundary.
+- Keep MCP tools read-only; AI-driven mutation is outside the server boundary.
 - Do not add ordinary delete/archive operations.
 - Use immutable gem-owned public values and typed errors.
 

data/README.md

@@ -1,5 +1,10 @@
 # Analytics Ops
 
+[![Gem Version](https://img.shields.io/gem/v/analytics_ops.svg)](https://rubygems.org/gems/analytics_ops)
+[![CI](https://github.com/nelsonchaves/analytics_ops/actions/workflows/ci.yml/badge.svg)](https://github.com/nelsonchaves/analytics_ops/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/analytics_ops)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE.txt)
+
 **Google Analytics 4 configuration as code and reporting for Ruby and Rails.**
 
 Analytics Ops gives you a review-first way to inspect GA4, detect drift, run
@@ -19,7 +24,7 @@ analytics-ops overview
 
 `setup` lists the properties the service account can access, lets you choose
 one, and creates the smallest valid `config/analytics_ops.yml` for the default
-`production` profile. It securely remembers the key's path, so every later
+`production` profile. It securely remembers the connection, so every later
 command works without another authentication option. You do not need
 `gcloud`, browser authorization, a property ID, or hand-written YAML.
 
@@ -27,6 +32,20 @@ command works without another authentication option. You do not need
 traffic acquisition, landing pages, and devices for the previous 28 complete
 days. Both commands are read-only in Google Analytics.
 
+After setup, everyday use stays short:
+
+```bash
+analytics-ops report traffic --last 7
+analytics-ops overview --compare
+analytics-ops portfolio
+analytics-ops health
+```
+
+`--last`, `--from`, `--to`, and `--compare` make date changes easy.
+`portfolio` shows users, sessions, and key events across every configured
+property. `health` checks traffic, expected events, attribution quality,
+quota, and configuration drift without changing GA4.
+
 ## Google Analytics setup (first time only)
 
 The setup is easier when you keep these four separate things in mind:
@@ -148,7 +167,7 @@ For an application that uses Bundler, add:
 
 ```ruby
 # Gemfile
-gem "analytics_ops", "~> 0.2", group: :development
+gem "analytics_ops", "~> 0.3", group: :development
 ```
 
 Then run:
@@ -166,7 +185,7 @@ Setup:
 - lists the GA4 properties the service account can access
 - lets you choose a property
 - creates `config/analytics_ops.yml`
-- remembers only the key's absolute path in
+- remembers named connections and profile choices, using only key paths, in
   `~/.config/analytics_ops/connection.json`
 
 ### H. Verify the connection with read-only commands
@@ -174,7 +193,9 @@ Setup:
 ```bash
 bundle exec analytics-ops doctor
 bundle exec analytics-ops properties
+bundle exec analytics-ops profiles
 bundle exec analytics-ops overview
+bundle exec analytics-ops portfolio
 bundle exec analytics-ops report traffic --json
 bundle exec analytics-ops realtime
 bundle exec analytics-ops audit
@@ -203,7 +224,7 @@ reviewed a saved plan.
 - **Permission denied:** Grant Viewer or Editor inside GA4. A Google Cloud IAM
   role does not grant access to GA4 data.
 - **“This app is blocked” opens in a browser:** That is an obsolete OAuth
-  flow. Analytics Ops 0.2 uses a service-account JSON key and does not launch
+  flow. Analytics Ops uses a service-account JSON key and does not launch
   browser authorization.
 - **Key unavailable:** Run setup again with the key's new absolute path.
 - **Key creation disabled:** An organization policy may prohibit downloaded
@@ -227,6 +248,75 @@ analytics-ops properties
 analytics-ops discover # includes data streams
 ```
 
+## More than one property or client
+
+Setup can safely add another profile to the same configuration:
+
+```bash
+analytics-ops setup \
+  --profile client_b \
+  --connection client_b \
+  --service-account /secure/client-b/service-account.json
+
+analytics-ops profiles
+analytics-ops connections
+analytics-ops use client_b
+analytics-ops overview
+```
+
+The selected profile and its named Google connection are remembered for this
+configuration. Nothing secret enters the YAML. Use `analytics-ops portfolio`
+for one read-only totals table across all configured properties, or:
+
+```bash
+analytics-ops portfolio report traffic
+analytics-ops portfolio health
+```
+
+Those commands isolate per-property failures and use bounded concurrency.
+Optional profile labels make client and brand results easier to identify.
+
+## Custom reports without Ruby
+
+Discover valid property-specific fields, then run a report:
+
+```bash
+analytics-ops reports
+analytics-ops fields event
+analytics-ops report custom \
+  --dimension eventName \
+  --metric eventCount \
+  --where eventName=purchase \
+  --last 7
+```
+
+Saved report recipes can include nested filters and ordering in
+`config/analytics_ops.yml`. Large exports use explicit bounded pagination:
+
+```bash
+analytics-ops report traffic \
+  --all \
+  --max-rows 100000 \
+  --output tmp/traffic.csv
+```
+
+See [Reports](docs/reports.md) and [Analytics health](docs/health.md).
+
+## Ask ChatGPT, Codex, or Claude
+
+Analytics Ops includes a local MCP server with read-only tools only:
+
+```bash
+analytics-ops mcp --config /absolute/path/to/config/analytics_ops.yml
+```
+
+It can list properties and report fields, audit configuration and governance,
+check health, and read overviews, portfolios, saved or custom reports,
+realtime events, and explicitly configured BigQuery/funnel results. It has no
+`plan`, `apply`, create, update, or delete tool. See
+[ChatGPT, Codex, and Claude](docs/ai-connections.md) for the copy-and-paste
+connection commands and the data-sharing boundary.
+
 ## The safe change workflow
 
 ```text
@@ -257,21 +347,37 @@ what failed, and what remains.
 | Command | Purpose | Remote writes? |
 | --- | --- | --- |
 | `analytics-ops setup --service-account PATH` | Connect, choose a property, and create minimal configuration | No |
+| `analytics-ops connections` | List saved connection names without exposing key paths | No |
+| `analytics-ops profiles` | List configured properties and their connections | No |
+| `analytics-ops use NAME` | Select a profile and connection locally | No |
 | `analytics-ops properties` | List accessible accounts and properties without configuration | No |
 | `analytics-ops doctor` | Check configuration, credentials, APIs, property access, clients, and clock | No |
 | `analytics-ops discover` | List accessible accounts, properties, and streams without configuration | No |
 | `analytics-ops overview` | Show five useful reports in one bounded batch | No |
+| `analytics-ops portfolio` | Compare totals across every configured property | No |
+| `analytics-ops portfolio report NAME` | Run one report across configured properties | No |
+| `analytics-ops portfolio health` | Check every configured property with isolated failures | No |
+| `analytics-ops health` | Check traffic, events, attribution quality, quota, and drift | No |
 | `analytics-ops snapshot` | Print normalized managed remote state | No |
 | `analytics-ops audit` | Show drift without writing a plan file | No |
 | `analytics-ops plan --output FILE` | Review and save deterministic changes | No |
 | `analytics-ops apply FILE` | Apply one reviewed, non-stale plan | **Yes** |
 | `analytics-ops verify` | Check convergence | No |
 | `analytics-ops report NAME` | Run a built-in standard report | No |
+| `analytics-ops reports` | List built-in and saved report recipes | No |
+| `analytics-ops fields SEARCH` | Find property-aware dimensions and metrics | No |
+| `analytics-ops compatibility NAME` | Check whether a report's fields work together | No |
 | `analytics-ops realtime` | Run the realtime-events report | No |
+| `analytics-ops governance` | Audit broader Alpha GA4 settings | No |
+| `analytics-ops changes` | Read de-identified recent configuration changes | No |
+| `analytics-ops access` | Read aggregate Data API access-quota usage | No |
+| `analytics-ops raw NAME` | Run an optional fixed, cost-capped BigQuery recipe | No |
+| `analytics-ops funnel NAME` | Run an optional aggregate ordered funnel | No |
+| `analytics-ops mcp` | Start the strictly read-only local AI connection | No |
 | `analytics-ops schema --format json` | Print the configuration schema | No |
 
-Use `--json` or `--format json` for automation. CSV is available only for
-individual reports:
+Use `--json` or `--format json` for automation. CSV is available for report
+results, portfolio reports, and optional BigQuery/funnel results:
 
 ```bash
 bundle exec analytics-ops report landing-pages --csv
@@ -280,6 +386,14 @@ bundle exec analytics-ops report landing-pages --csv
 Friendly `traffic` and `landing-pages` aliases leave the original
 `traffic_acquisition` and `landing_pages` names fully supported.
 
+Choose report dates without editing Ruby:
+
+```bash
+analytics-ops report traffic --last 7
+analytics-ops report traffic --from 2026-07-01 --to 2026-07-07
+analytics-ops overview --last 30 --compare
+```
+
 See [Commands](docs/commands.md) for every option and exit status.
 
 ## IDs: the quick distinction
@@ -309,8 +423,14 @@ plan.write("tmp/ga4-plan.json")
 report = workspace.report("calculator_completions")
 report.rows.each { |row| puts row.fetch("eventCount") }
 
+ranges = AnalyticsOps::Reports::Period.resolve(last_days: 7, compare: true)
+comparison = workspace.report("traffic", date_ranges: ranges)
+
 overview = workspace.overview
 puts overview.report("overview_totals").rows
+
+health = workspace.health
+puts health.findings.map(&:message)
 ```
 
 Loading the gem, loading YAML, and booting Rails do not contact Google.
@@ -324,12 +444,14 @@ gem "analytics_ops", require: "analytics_ops/rails", group: :development
 ```
 
 ```bash
+bin/rails generate analytics_ops:install
 bundle exec analytics-ops setup \
-  --profile development \
   --service-account /absolute/path/to/service-account.json
-bin/rails generate analytics_ops:install
 bin/rake analytics:doctor
 bin/rake analytics:overview
+bin/rake analytics:portfolio
+bin/rake analytics:health
+bin/rake analytics:governance
 bin/rake 'analytics:report[traffic_acquisition]'
 ```
 
@@ -340,12 +462,14 @@ boot-time network calls. See [Rails integration](docs/rails.md).
 ## What Analytics Ops does not do
 
 - It does not inject browser analytics or manage consent banners.
-- It stores only the service-account key's path in a mode-`0600` user file;
-  it never copies the key, tokens, or report rows.
+- It stores only named service-account key paths in a mode-`0600` user file;
+  it never copies keys, tokens, or report rows.
 - It does not delete accounts, properties, streams, or unmanaged resources.
 - It does not claim to manage settings that Google exposes only in the UI.
-- Experimental declarations are findings only in version 0.2.0; they are not
-  silently applied through Alpha APIs.
+- Experimental governance features are read-only and never enter ordinary
+  plans or apply.
+- Optional BigQuery support runs only fixed `SELECT` recipes behind a required
+  dry run and byte cap; it does not accept arbitrary SQL.
 
 ## Documentation
 
@@ -355,7 +479,11 @@ boot-time network calls. See [Rails integration](docs/rails.md).
 | [Live smoke test](docs/live-smoke-test.md) | Real-app read-only verification and release gate |
 | [Configuration](docs/configuration.md) | Complete strict YAML contract |
 | [Commands](docs/commands.md) | CLI syntax, formats, and exit statuses |
-| [Reports](docs/reports.md) | Built-in recipes and GA reporting limitations |
+| [Reports](docs/reports.md) | Built-in, saved, custom, and exported reports |
+| [Analytics health](docs/health.md) | Deterministic traffic and data-quality checks |
+| [Governance](docs/governance.md) | Experimental read-only Admin checks |
+| [BigQuery and funnels](docs/bigquery.md) | Optional cost-capped raw-data recipes |
+| [ChatGPT, Codex, and Claude](docs/ai-connections.md) | Strictly read-only local AI connection |
 | [Rails](docs/rails.md) | Generator and Rake tasks |
 | [Safety](docs/safety.md) | Plans, stale-state protection, rollback, and credentials |
 | [Plan format](docs/plan-format.md) | Version-1 JSON contract |

data/SECURITY.md

@@ -40,12 +40,21 @@ Analytics Ops:
 - rejects stale and cross-property plans
 - excludes delete/archive operations from ordinary plans
 - never logs report results automatically
+- exposes only read-only, non-destructive tools through MCP and has no AI
+  mutation tool
+- validates custom report fields against live property metadata and
+  compatibility before execution
+- omits actor email and full resource bodies from change-history output
+- allows only fixed optional BigQuery SELECT recipes, with a dry run,
+  mandatory byte cap, bounded rows, and no arbitrary SQL input
 - has no telemetry, private-key/token store, database, or browser injection
 - publishes through RubyGems Trusted Publishing without a stored API key
 
 Plan files still describe operational configuration and are created with mode
-0600. Report output may contain sensitive aggregate data and should be handled
-under the operator's data policy.
+0600. Report, governance, BigQuery, and funnel output may contain sensitive
+aggregate data and should be handled under the operator's data policy. MCP
+tool results are sent to the connected AI provider; credentials and saved key
+paths are not.
 
 ## Operator responsibilities
 

data/docs/ai-connections.md

@@ -0,0 +1,192 @@
+# ChatGPT, Codex, and Claude
+
+Analytics Ops can let an AI read your Google Analytics data through the Model
+Context Protocol (MCP). The connection is deliberately read-only.
+
+The simple idea is:
+
+```text
+ChatGPT, Codex, or Claude
+  → local Analytics Ops MCP process
+  → Google Analytics read-only APIs
+```
+
+The AI can inspect and explain data. It cannot change GA4 through this
+connection.
+
+## Before connecting
+
+Finish normal Analytics Ops setup first:
+
+```bash
+analytics-ops doctor
+analytics-ops overview
+```
+
+Both should work. Then identify:
+
+- the absolute Analytics Ops config path
+- the command that starts Analytics Ops
+
+For a Rails or Bundler application, the generated binstub is easiest:
+
+```text
+/Users/example/sites/my_app/bin/analytics-ops
+```
+
+All paths below are fake. Replace them with your own absolute paths.
+
+## ChatGPT desktop and Codex
+
+The ChatGPT desktop app, Codex CLI, and Codex IDE extension share local MCP
+configuration on the same Codex host.
+
+The fastest setup is:
+
+```bash
+codex mcp add analytics-ops -- \
+  /Users/example/sites/my_app/bin/analytics-ops \
+  mcp \
+  --config /Users/example/sites/my_app/config/analytics_ops.yml
+```
+
+Then restart ChatGPT desktop or Codex. In ChatGPT desktop, you can also open
+**Settings → MCP servers → Add server**, choose **STDIO**, and enter the same
+command and arguments.
+
+Check the saved server with:
+
+```bash
+codex mcp list
+```
+
+## Claude Code
+
+Add the same local stdio server:
+
+```bash
+claude mcp add --transport stdio --scope user analytics-ops -- \
+  /Users/example/sites/my_app/bin/analytics-ops \
+  mcp \
+  --config /Users/example/sites/my_app/config/analytics_ops.yml
+```
+
+Restart Claude Code, then use `/mcp` to check the connection.
+
+## What you can ask
+
+Examples:
+
+- “Show my Analytics overview for the last 7 complete days.”
+- “Compare traffic with the preceding 30 days.”
+- “Which landing pages have the most sessions?”
+- “Show totals across all configured properties.”
+- “Check every property for a large traffic drop.”
+- “Find report fields related to revenue.”
+- “Run an event-count report filtered to purchases.”
+- “Check whether my required data-redaction settings are enabled.”
+- “Audit my GA4 configuration and explain any drift.”
+- “Are events arriving in realtime?”
+
+The AI can call these tools:
+
+- list local profiles and connection names
+- list accessible GA4 properties
+- run doctor
+- read a normalized configuration snapshot
+- audit configuration drift
+- list built-in and configured report recipes
+- search property-aware dimensions and metrics
+- check report-field compatibility
+- run bounded built-in, configured, or one-off custom reports
+- run overview, generalized portfolio reports, and portfolio health
+- run deterministic traffic and data-quality health checks
+- audit experimental governance settings
+- read an aggregate Data API quota-access report without user email or IP
+- read realtime event counts
+- run a fixed cost-capped BigQuery recipe or configured aggregate funnel when
+  that optional feature is present
+
+There are 21 tools. Every one is explicitly marked read-only and
+non-destructive. BigQuery tools accept only fixed recipe or funnel names; they
+do not accept SQL.
+
+## What the AI cannot do
+
+The MCP server has no tools for:
+
+- `plan`
+- `apply`
+- create or update
+- delete or archive
+- reading a credential file or key path
+- reading user-email change history
+- arbitrary SQL
+
+Every tool is marked read-only and non-destructive in MCP metadata. Starting
+the server does not load a credential or contact Google. Google access begins
+only after the AI calls a read tool.
+
+If a recommended change looks useful, leave the AI connection and use the
+normal human-reviewed CLI workflow:
+
+```bash
+analytics-ops plan --output tmp/ga4-plan.json
+less tmp/ga4-plan.json
+analytics-ops apply tmp/ga4-plan.json
+```
+
+The AI cannot perform that final command through MCP.
+
+## Privacy boundary
+
+The service-account JSON key, access token, authorization header, and saved
+key path stay local and are never returned by an MCP tool.
+
+Requested tool results do go to the connected AI product. Those results can
+include:
+
+- GA4 property and account names
+- property IDs
+- configuration values
+- traffic, event, and landing-page report rows
+- optional BigQuery recipe and aggregate funnel rows
+
+Connect only an AI account or workspace whose data policy is appropriate for
+your analytics information. Do not ask the model to repeat or store sensitive
+report data unnecessarily.
+
+## ChatGPT on the web
+
+Local stdio is the easiest route for ChatGPT desktop, Codex, and Claude Code.
+ChatGPT on the web does not read your local MCP configuration directly.
+
+If web access is required, OpenAI's official
+[Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
+can forward an OpenAI-hosted tunnel to the same local stdio command over an
+outbound-only connection. It requires a Platform tunnel ID, a runtime API key,
+the `tunnel-client`, and the appropriate ChatGPT workspace permissions. This
+is an optional advanced deployment; Analytics Ops does not need a public
+server or inbound firewall port.
+
+## Troubleshooting
+
+- **Server starts and appears to hang:** Correct. Stdio MCP waits silently for
+  protocol messages. The AI client starts and controls it.
+- **Config not found:** Use an absolute `--config` path.
+- **Gem not found:** Use the application's absolute `bin/analytics-ops`
+  binstub, or install the gem globally.
+- **No properties:** Add the exact service-account email to the correct GA4
+  account or property.
+- **More than one connection:** Run `analytics-ops profiles` and
+  `analytics-ops use PROFILE --connection NAME`.
+- **Changed MCP settings:** Restart the AI client.
+- **Need to inspect protocol tools:** `codex mcp list` or Claude Code `/mcp`
+  shows the configured local server.
+
+Official client references:
+
+- [OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp)
+- [OpenAI Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
+- [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
+- [Model Context Protocol transports](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)