# What GA4 Reporting Metrics Are Exposed Through MCP Tools? Complete Reference

> Discover which GA4 reporting metrics are exposed through Open SEO's MCP tools. Access sessions, users, revenue, and more in this complete reference.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: api-reference
- Published: 2026-08-10

---

**Open SEO's MCP tools expose 11 fixed GA4 reporting metrics across three read-only tools: sessions, activeUsers, engagedSessions, engagementRate, keyEvents, sessionKeyEventRate, transactions, purchaseRevenue, screenPageViews, userEngagementDuration, and totalUsers.**

Open SEO implements a controlled **Google Analytics 4 (GA4) MCP integration** that deliberately limits metric exposure to a predefined, read-only set. This design prioritizes security and predictable behavior over flexibility. The MCP (Modular Command-Protocol) tools are defined in [[`specs/0007-google-analytics-mcp-integration.md`](https://github.com/every-app/open-seo/blob/main/specs/0007-google-analytics-mcp-integration.md)](https://github.com/every-app/open-seo/blob/main/specs/0007-google-analytics-mcp-integration.md) and implemented across three dedicated service layers that hard-code every dimension and metric.

## The Three GA4 MCP Tools and Their Metrics

Open SEO surfaces GA4 data through three specialized MCP tools. Each tool serves a distinct analytical purpose and returns a fixed subset of **GA4 reporting metrics**.

### `get_google_analytics_organic_landing_pages`

This tool analyzes organic search entry points and returns the most comprehensive metric set.

| Aspect | Details |
|--------|---------|
| **GA4 dimensions** | `hostName`, `landingPage` |
| **GA4 metrics exposed** | `sessions`, `activeUsers`, `engagedSessions`, `engagementRate`, `keyEvents`, `sessionKeyEventRate`, `transactions`, `purchaseRevenue` |

The service layer in [[`src/shared/ga4.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts) constructs a `runReport` call with `keepEmptyRows: false` and `returnPropertyQuota: true`. No custom filtering or additional metrics can be injected.

```typescript
const organic = await callMcpTool('get_google_analytics_organic_landing_pages', {
  projectId: 'proj_123',
  startDate: '2024-05-01',
  endDate: '2024-05-28',
});
/* Returns:
{
  hostName: 'example.com',
  landingPage: '/product',
  sessions: 124,
  activeUsers: 98,
  engagedSessions: 87,
  engagementRate: 0.71,
  keyEvents: 12,
  sessionKeyEventRate: 0.10,
  transactions: 3,
  purchaseRevenue: 45.67
}
*/

```

### `get_google_analytics_page_performance`

This tool tracks content engagement with optional daily granularity.

| Aspect | Details |
|--------|---------|
| **GA4 dimensions** | `hostName`, `pagePath` (optional `date`) |
| **GA4 metrics exposed** | `screenPageViews`, `activeUsers`, `userEngagementDuration`, `keyEvents` |

The optional `includeDate` parameter toggles the `date` dimension for time-series analysis. The `channel` parameter accepts `'all'` or `'organic_search'` but does not modify the returned metrics.

```typescript
const perf = await callMcpTool('get_google_analytics_page_performance', {
  projectId: 'proj_123',
  channel: 'organic_search',
  includeDate: true,
});
/* Returns:
{
  hostName: 'example.com',
  pagePath: '/blog/post',
  date: '2024-05-15',
  screenPageViews: 256,
  activeUsers: 210,
  userEngagementDuration: 345.2,
  keyEvents: 5
}
*/

```

### `get_google_analytics_key_events`

This tool breaks down conversion events with flexible dimensionality.

| Aspect | Details |
|--------|---------|
| **Base GA4 dimensions** | `eventName` |
| **Conditional dimensions** | `hostName`, `landingPage` (when `breakdown: 'event_and_landing_page'`) |
| **GA4 metrics exposed** | `keyEvents`, `totalUsers` |

The `breakdown` parameter controls dimension granularity without affecting metric selection. This is the only tool that exposes `totalUsers` rather than `activeUsers`.

```typescript
const events = await callMcpTool('get_google_analytics_key_events', {
  projectId: 'proj_123',
  breakdown: 'event_and_landing_page',
});
/* Returns:
{
  eventName: 'purchase',
  hostName: 'example.com',
  landingPage: '/checkout',
  keyEvents: 8,
  totalUsers: 7
}
*/

```

## Why GA4 Metrics Are Hard-Coded in Open SEO

The **fixed metric design** is intentional and enforced at multiple architectural layers:

- **Zod validation schemas** in [[`src/shared/ga4.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts) reject any parameters beyond the documented inputs
- **Date range clamping** prevents excessive data extraction
- **Quota and privacy metadata** are normalized in every response
- **No arbitrary dimensions, filters, or ordering** can be supplied by MCP clients

This implementation differs from direct GA4 Data API access, which allows custom `runReport` configurations. Open SEO's MCP layer trades flexibility for **predictable, auditable behavior** suitable for automated agents.

## Complete GA4 Metrics Reference Table

| Metric | Tool(s) Exposed | Description |
|--------|-----------------|-------------|
| `sessions` | `get_google_analytics_organic_landing_pages` | Total session count |
| `activeUsers` | Organic landing pages, Page performance | Distinct users with engagement |
| `engagedSessions` | Organic landing pages | Sessions exceeding engagement threshold |
| `engagementRate` | Organic landing pages | Engaged sessions / Total sessions |
| `keyEvents` | All three tools | Count of marked key events |
| `sessionKeyEventRate` | Organic landing pages | Key events / Sessions |
| `transactions` | Organic landing pages | Completed purchase events |
| `purchaseRevenue` | Organic landing pages | Revenue from transactions |
| `screenPageViews` | Page performance | Total page/screen views |
| `userEngagementDuration` | Page performance | Seconds of active engagement |
| `totalUsers` | Key events | Distinct users (event-scoped) |

## Key Implementation Files

| File | Role |
|------|------|
| [[`specs/0007-google-analytics-mcp-integration.md`](https://github.com/every-app/open-seo/blob/main/specs/0007-google-analytics-mcp-integration.md)](https://github.com/every-app/open-seo/blob/main/specs/0007-google-analytics-mcp-integration.md) | Formal MCP contract specifying tools, inputs, and exposed GA4 metrics |
| [[`src/server/mcp/tools/google-analytics-tools.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/google-analytics-tools.ts)](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/google-analytics-tools.ts) | MCP tool registration and `Ga4Service` wiring |
| [[`src/shared/ga4.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts) | GA4 client, fixed `runReport` builders, Zod schemas |
| [[`src/db/pg/ga4.schema.ts`](https://github.com/every-app/open-seo/blob/main/src/db/pg/ga4.schema.ts)](https://github.com/every-app/open-seo/blob/main/src/db/pg/ga4.schema.ts) | Database schema for GA4 connection metadata |

## Summary

- **11 GA4 reporting metrics** are exposed through Open SEO's MCP tools: `sessions`, `activeUsers`, `engagedSessions`, `engagementRate`, `keyEvents`, `sessionKeyEventRate`, `transactions`, `purchaseRevenue`, `screenPageViews`, `userEngagementDuration`, and `totalUsers`
- **Three read-only tools** distribute these metrics: organic landing pages (8 metrics), page performance (4 metrics), and key events (2 metrics)
- **Hard-coded implementation** in [[`src/shared/ga4.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts) prevents arbitrary metric or dimension selection
- **No write access**, real-time reports, custom dimensions, or audience data is available through the MCP interface

## Frequently Asked Questions

### Can I request additional GA4 metrics beyond the 11 exposed?

No. The MCP tools in Open SEO implement a fixed contract defined in [[`specs/0007-google-analytics-mcp-integration.md`](https://github.com/every-app/open-seo/blob/main/specs/0007-google-analytics-mcp-integration.md)](https://github.com/every-app/open-seo/blob/main/specs/0007-google-analytics-mcp-integration.md). The Zod validation schemas in [[`src/shared/ga4.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/ga4.ts) explicitly reject any parameters attempting to modify the metric set, dimensions, or filters. For custom GA4 reporting, you must use the GA4 Data API directly rather than Open SEO's MCP layer.

### Why does `get_google_analytics_key_events` use `totalUsers` instead of `activeUsers`?

The metric selection reflects GA4's data model for event-scoped analysis. When breaking down by `eventName` (and optionally landing page), `totalUsers` counts distinct users who triggered the specific event, while `activeUsers` would be property-scoped. This distinction ensures accurate conversion attribution in the key events tool without double-counting users across multiple events.

### Are real-time GA4 reports available through MCP tools?

No. All three GA4 MCP tools query the standard GA4 Data API with historical date ranges. The implementation uses `runReport` with `keepEmptyRows: false` and does not expose the real-time reporting API. Real-time metrics such as `activeUsers` in the last 30 minutes or `screenPageViews` in the last 60 minutes are not available through Open SEO's MCP interface.