MCP Integration Architecture Reference Guide

Version: 1.0.0 (V6.9.1) Last Updated: February 5, 2026 Author: MIZ OKI Platform Team

Overview

This document provides the reference architecture for MCP (Model Context Protocol) integrations across Google Ads, Meta, GA4, Salesforce Marketing Cloud, and other marketing platforms. It covers:

  1. Unified PII Hashing - Platform-compliant SHA-256 hashing
  2. Skill.json Schemas - JSON Schema definitions for capability registration
  3. Retry Policy Matrix - Idempotency-tagged retry strategies
  4. OAuth Scope Registry - Least-privilege scope mappings

Recent MCP Ecosystem Updates (Verified)

Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                        MCP Integration Architecture                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌────────────────┐    ┌────────────────┐    ┌────────────────┐            │
│  │   PIIHasher    │    │ SkillRegistry  │    │ RetryPolicyMtx │            │
│  │                │    │                │    │                │            │
│  │ • Gmail norm   │    │ • GA4 MP       │    │ • Exp backoff  │            │
│  │ • E.164 phone  │    │ • GA4 Data API │    │ • Idempotency  │            │
│  │ • Name/Address │    │ • Google Ads   │    │ • Circuit break│            │
│  │ • Customer Mtch│    │ • Meta CAPI    │    │ • Per-endpoint │            │
│  │ • Meta CAPI fmt│    │ • Meta Audience│    │   policies     │            │
│  └───────┬────────┘    └───────┬────────┘    └───────┬────────┘            │
│          │                     │                     │                      │
│          └─────────────────────┼─────────────────────┘                      │
│                                │                                            │
│                    ┌───────────▼───────────┐                               │
│                    │ MCPIntegrationOrchstr │                               │
│                    │                       │                               │
│                    │ • execute_with_retry  │                               │
│                    │ • idempotency_manager │                               │
│                    │ • skill_registry      │                               │
│                    └───────────┬───────────┘                               │
│                                │                                            │
│          ┌─────────────────────┼─────────────────────┐                     │
│          │                     │                     │                      │
│  ┌───────▼────────┐   ┌───────▼────────┐   ┌───────▼────────┐             │
│  │   Google Ads   │   │     Meta       │   │      GA4       │             │
│  │   API v22      │   │   API v24      │   │   MP / Data    │             │
│  │                │   │                │   │                │             │
│  │ Customer Match │   │ CAPI Events    │   │ Events/Reports │             │
│  │ Conversions    │   │ Custom Audience│   │ MP EU Endpoint │             │
│  └────────────────┘   └────────────────┘   └────────────────┘             │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

1. Unified PII Hashing

Overview

All platforms require SHA-256 hashing of PII before upload. However, each platform has specific normalization requirements that must be followed for optimal match rates.

Platform Normalization Rules

Field Google Ads Meta GA4
Email Lowercase, trim, Gmail dot-strip, remove +tag Lowercase, trim N/A (use client_id)
Phone E.164 (digits only with country code) E.164 (digits only) N/A
First Name Lowercase, trim Lowercase, trim N/A
Last Name Lowercase, trim Lowercase, trim N/A
Street Lowercase, trim, expand abbreviations Lowercase, trim N/A
City Lowercase, trim Lowercase, trim N/A
State 2-letter abbreviation 2-letter abbreviation N/A
Postal Code First 5 digits (US) Full code, no spaces N/A
Country ISO 2-letter code Lowercase ISO code N/A

Gmail Normalization

Gmail addresses require special handling:

# Gmail domains that require dot-stripping
GMAIL_DOMAINS = {"gmail.com", "googlemail.com"}

# Example normalization
"John.Doe@Gmail.com"     → "johndoe@gmail.com"     → SHA256
"jane+promo@gmail.com"   → "jane@gmail.com"        → SHA256
"user@example.com"       → "user@example.com"      → SHA256 (no change)

Phone E.164 Normalization

# Examples
"+1 (555) 123-4567"  → "15551234567"  → SHA256
"555-123-4567"       → "15551234567"  → SHA256 (default US)
"+44 20 7946 0958"   → "442079460958" → SHA256

Usage Examples

from mcp_integration_architecture import PIIHasher, Platform

hasher = PIIHasher()

# Hash for Customer Match upload
result = hasher.hash_for_customer_match(
    email="John.Doe@Gmail.com",
    phone="+1 (555) 123-4567",
    first_name="John",
    last_name="Doe",
    country="US",
    postal_code="94105"
)

# Returns:
# {
#     "hashedEmail": "abc123...",      # SHA256 of "johndoe@gmail.com"
#     "hashedPhoneNumber": "def456...", # SHA256 of "15551234567"
#     "hashedFirstName": "...",
#     "hashedLastName": "...",
#     "countryCode": "US",
#     "postalCode": "94105"
# }

Meta Conversions API

# Hash for Meta CAPI
result = hasher.hash_for_meta_capi(
    email="user@example.com",
    phone="+15551234567",
    first_name="Jane",
    last_name="Smith",
    city="San Francisco",
    state="California",
    country="US",
    postal_code="94105",
    external_id="cust_12345"
)

# Returns:
# {
#     "em": ["abc123..."],    # Hashed email (array format)
#     "ph": ["def456..."],    # Hashed phone (array format)
#     "fn": "...",
#     "ln": "...",
#     "ct": "...",            # Hashed city
#     "st": "...",            # Hashed state (normalized to 'ca')
#     "country": "...",
#     "zp": "...",
#     "external_id": "..."
# }

2. Skill.json Schema Definitions

Schema Structure

Each skill is defined using JSON Schema with MCP extensions:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://mizoki.com/schemas/skills/ga4.measurement_protocol.send_event:v2",
  "title": "GA4 Measurement Protocol - Send Event",
  "description": "Send server-side events to GA4 via Measurement Protocol",
  "type": "object",
  "properties": {
    "measurement_id": {
      "type": "string",
      "description": "GA4 Measurement ID (G-XXXXXXX)",
      "pattern": "^G-[A-Z0-9]+$"
    },
    "api_secret": {
      "type": "string",
      "description": "GA4 API Secret"
    },
    "client_id": {
      "type": "string",
      "description": "Client ID (from _ga cookie or generated)"
    },
    "events": {
      "type": "array",
      "description": "Array of events to send"
    },
    "use_eu_endpoint": {
      "type": "boolean",
      "description": "Use EU regional endpoint",
      "default": false
    }
  },
  "required": ["measurement_id", "api_secret", "client_id", "events"],
  "x-mizoki": {
    "version": "2.0.0",
    "platform": "ga4",
    "required_scopes": [],
    "rate_limit": {
      "per_minute": 60,
      "per_day": 100000
    },
    "retry": {
      "strategy": "exponential_backoff",
      "max_retries": 3,
      "idempotency_mode": "dedup_return"
    },
    "data_classification": "pii",
    "pii_fields": ["user_id", "client_id"],
    "tags": ["analytics", "measurement", "ga4", "server-side"]
  }
}

Registered Skills

Skill ID Platform Description
ga4.measurement_protocol.send_event:v2 GA4 Server-side event tracking
ga4.data_api.run_report:v1 GA4 Analytics reporting
google_ads.customer_match.upload:v18 Google Ads Customer Match list upload
meta.capi.send_event:v21 Meta Conversions API events
meta.custom_audience.upload:v21 Meta Custom Audience upload

OAuth Scope Requirements

Platform Operation Required Scopes
GA4 Data API Read reports analytics.readonly
GA4 Data API Edit properties analytics.edit
GA4 MP Send events None (API Secret auth)
Google Ads Read campaigns adwords.readonly
Google Ads Mutate campaigns adwords
Meta CAPI events ads_management
Meta Custom Audiences ads_management

3. Retry Policy Matrix

Platform Defaults

Platform Strategy Max Retries Base Delay Max Delay Idempotency
Google Ads Exponential 3 2.0s 60s Strict
Meta Exponential 3 1.0s 30s Dedup Return
GA4 Exponential 3 1.0s 30s Allow Retry
Salesforce Exponential 3 2.0s 60s Strict

Endpoint-Specific Overrides

Endpoint Strategy Max Retries Base Delay Idempotency
google_ads.campaigns.mutate Exponential 2 3.0s Strict
google_ads.campaigns.list Exponential 5 1.0s Allow Retry
meta.capi.send_event Exponential 3 1.0s Dedup Return
ga4.measurement_protocol.send_event Exponential 3 0.5s Dedup Return
ga4.data_api.run_report Exponential 3 1.0s Allow Retry

Retryable Status Codes

Platform Retryable Codes
Google Ads 429, 500, 503
Meta 429, 500, 503, 613 (rate limit)
GA4 429, 500, 503

Idempotency Modes

Mode Behavior
strict Reject duplicate requests entirely
dedup_return Return cached response for duplicates
allow_retry Allow retry with same key (increment attempt counter)
none No idempotency checking

Backoff Calculation

# Exponential backoff with jitter
delay = min(base_delay * (2 ** (attempt - 1)), max_delay)
delay *= (1 + random() * 0.25)  # 0-25% jitter

4. Idempotency Key Generation

Key Format

{endpoint}:{request_hash}:{client_key_or_uuid}

Examples: - meta.capi.send_event:a1b2c3d4:evt_12345 - google_ads.campaigns.mutate:e5f6g7h8:op_67890

Request Hash Computation

def _hash_request(payload: Dict[str, Any]) -> str:
    canonical = json.dumps(payload, sort_keys=True, default=str)
    return hashlib.sha256(canonical.encode()).hexdigest()[:16]

TTL Configuration

5. MCP Tools Reference

PII Hashing Tools

Tool Description
pii_hash_email Hash email with platform normalization
pii_hash_phone Hash phone with E.164 normalization
pii_hash_for_customer_match Hash for Google Ads Customer Match format
pii_hash_for_meta_capi Hash for Meta CAPI format

Skill Management Tools

Tool Description
skill_list List registered skills by platform
skill_get_schema Get JSON Schema for a skill

Retry Policy Tools

Tool Description
retry_get_policy Get policy for platform/endpoint
retry_get_matrix Get full retry policy matrix

Idempotency Tools

Tool Description
idempotency_generate_key Generate idempotency key
mcp_integration_status Get module status

6. Integration with MCP Connector Registry V2

The MCP Integration Architecture integrates with the existing Connector Registry V2:

# Register skill as capability in V2 registry
from mcp_connector_registry_v2 import MCPConnectorRegistryV2
from mcp_integration_architecture import SkillSchemaRegistry

registry = MCPConnectorRegistryV2(firestore_client)
skill = SkillSchemaRegistry.ga4_send_event()

# Convert skill to capability descriptor
capability = {
    "id": skill.id,
    "name": skill.name,
    "description": skill.description,
    "platform": skill.platform.value,
    "input_schema": skill.to_json_schema(),
    "rate_limit": {
        "per_minute": skill.rate_limit_per_minute,
        "per_day": skill.rate_limit_per_day
    },
    "required_scopes": skill.required_scopes
}

await registry.register_capability(capability)

7. Environment Variables

Variable Description Default
ENABLE_MCP_INTEGRATION Enable/disable module true
IDEMPOTENCY_TTL_HOURS TTL for idempotency keys 48
GA4_MEASUREMENT_ID GA4 property ID -
GA4_API_SECRET GA4 MP API secret -
META_PIXEL_ID Meta Pixel ID -
META_ACCESS_TOKEN Meta access token -

8. Firestore Collections

Collection Purpose
mcp_pii_hashes Cached PII hashes (optional)
mcp_skill_registry Custom skill definitions
mcp_retry_state Retry attempt tracking
mcp_idempotency_keys Idempotency records

9. Best Practices

PII Handling

  1. Never log raw PII - Only log hashed values or partial masks
  2. Hash on server-side - Never trust client-side hashing
  3. Use platform-specific normalization - Match rates depend on it
  4. Document consent - Track consent signals alongside hashed data

Retry Policies

  1. Respect Retry-After headers - Platform-provided delays take precedence
  2. Use idempotency keys - Especially for mutate operations
  3. Implement circuit breakers - Prevent cascade failures
  4. Log all attempts - For debugging and audit

Skill Schemas

  1. Version your skills - Include version in skill ID
  2. Document PII fields - Mark which parameters contain PII
  3. Set appropriate rate limits - Don't exceed platform quotas
  4. Use least-privilege scopes - Only request necessary permissions

10. Version History

Version Date Changes
1.0.0 2026-01-12 Initial release with PIIHasher, SkillSchemas, RetryPolicies

This document is part of the MIZ OKI Platform documentation. For questions, contact the Platform Team.

Healthcare Operations Research Module (MIZOKI Integration)

A healthcare-specific autonomous research module is integrated via MCP service registry under adapter id healthcare_ops_research.

Tool endpoints exposed to Boss Agent orchestration:

This module operationalizes patient-pathway-resource graph loops for readmission risk, LOS variance, denial recurrence, and discharge-transition fragility using the same MCP invocation and governance model as other production adapters.

← All docsView source on GitHub →