Skip to main content
This page documents all headers accepted by the MCP Signal Server for signal collection.

​
Required Headers

HeaderDescription
x-zc-api-keyYour ZeroClick API key for authentication
x-zc-llm-modelLLM model identifier (e.g., openai/gpt-4o, anthropic/claude-sonnet-4.5)
Content-TypeMust be application/json
AcceptMust include application/json, text/event-stream

​
Authentication

The x-zc-api-key header is required for all requests: 
x-zc-api-key: YOUR_API_KEY
Obtain your API key from the ZeroClick Developer Portal (contact developers@zeroclick.ai for access). Requests without a valid API key will receive a 401 Unauthorized response.

​
User Context Headers

All user context headers use the x-zc-user-* prefix to clearly identify end-user information.

​
x-zc-user-id

x-zc-user-id: user-123
A unique identifier for the end user. This can be your internal user ID, a hashed value, or any consistent identifier.
  • Format: String, max 255 characters
  • Use case: Aggregate signals per user for personalization

​
x-zc-user-session-id

x-zc-user-session-id: session-abc-456
Current session or chat thread.
  • Format: String, max 255 characters
  • Use case: Group signals within a single conversation or browsing session

​
x-zc-user-locale

x-zc-user-locale: en-US
The end user’s locale or language preference.
  • Format: String, max 35 characters (BCP 47 language tag)
  • Use case: Localization and language-specific signal analysis
  • Examples: en-US, fr-FR, zh-Hans-CN

​
x-zc-grouping-id

x-zc-grouping-id: campaign-summer-2024
An optional grouping identifier for organizing signals.
  • Format: String, max 255 characters
  • Use case: Group signals by campaign, experiment, or custom segmentation

​
x-zc-user-ip

x-zc-user-ip: 192.168.1.1
The end user’s IP address.
  • Format: String, max 45 characters (supports IPv4 and IPv6)

​
x-zc-user-agent

x-zc-user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...
The end user’s browser or client user agent string.
  • Format: String, max 1000 characters
  • Use case: Device and browser analytics

​
Application Context Headers

​
x-zc-llm-model

x-zc-llm-model: openai/gpt-4o
Required. The LLM model used in your application.
  • Format: String, max 64 characters
Examples:
  • openai/gpt-4o - OpenAI GPT-4o
  • anthropic/claude-sonnet-4.5 - Anthropic Claude Sonnet 4.5
  • google/gemini-3-flash - Google Gemini 3.0 Flash
For consistency, we recommend using the model identifiers listed by Vercel.

​
Privacy-Safe PII Headers

For identity resolution across platforms, you can pass hashed PII values:
Never send raw email or phone values. Always hash with SHA256 before sending.

​
x-zc-user-email-sha256

x-zc-user-email-sha256: 5d41402abc4b2a76b9719d911017c592...
SHA256 hash of the user’s lowercase, trimmed email address.
  • Format: 64-character hexadecimal string
  • Preparation: SHA256(email.toLowerCase().trim())

​
x-zc-user-phone-sha256

x-zc-user-phone-sha256: 7d793037a0760186574b0282f2f435e7...
SHA256 hash of the user’s phone number in E.164 format.
  • Format: 64-character hexadecimal string
  • Preparation: SHA256(phone) where phone is in E.164 format (e.g., +14155551234)

​
Example: Full Header Set

const headers = {
  // Required
  "x-zc-api-key": "your-api-key",
  "Content-Type": "application/json",
  "Accept": "application/json, text/event-stream",

  // User context
  "x-zc-user-id": "user-12345",
  "x-zc-user-session-id": "session-abc-789",
  "x-zc-user-locale": "en-US",
  "x-zc-grouping-id": "campaign-summer-2024",
  "x-zc-user-ip": clientIp,
  "x-zc-user-agent": req.headers["user-agent"],

  // Application context
  "x-zc-llm-model": "openai/gpt-4o",

  // Privacy-safe PII (hashed)
  "x-zc-user-email-sha256": sha256(email.toLowerCase().trim()),
  "x-zc-user-phone-sha256": sha256(phone)
};

​
Hashing Helper

Here’s a helper function for SHA256 hashing: 
import { createHash } from "crypto";

function sha256(value: string): string {
  return createHash("sha256").update(value).digest("hex");
}

// Usage
const emailHash = sha256(email.toLowerCase().trim());
const phoneHash = sha256("+14155551234");  // E.164 format