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

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) 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) constructs a runReport call with keepEmptyRows: false and returnPropertyQuota: true. No custom filtering or additional metrics can be injected.

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.

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.

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) 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)	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)	MCP tool registration and Ga4Service wiring
[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)	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) 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). The Zod validation schemas in [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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}