Preamble

Title: Standardized Client Context Propagation (SCCP)
Author: Markus Cozowicz
Status: Draft
Type: Standards Track
Created: 2025-11-13

Abstract

This proposal defines a standardized mechanism for MCP clients to provide a minimal set of contextual metadata — the user’s local time zone, current timestamp, and locale — to servers on tool-call requests. This context enables servers and tools to interpret time-relative expressions (e.g., “yesterday”, “this month”) correctly, and to format or localize responses appropriately for the user.

Motivation

Tool calls and agent workflows often use relative time references (“today”, “last year”) or expect formatting/locale awareness (dates, numbers, currency). Without knowledge of the user’s timezone or locale, servers may default to UTC or server-local timezone and generic formatting, leading to:

• Inconsistent or surprising results (e.g., “yesterday” being off by one day due to timezone difference).
• Mistakes around daylight-saving transitions.
• Formatting that does not match the user’s regional expectations (e.g., date order, decimal separator, language).
  By standardizing a small set of metadata (timezone, currentTimestamp, locale), clients can provide the necessary context so that the server/tool can interpret the request as the user intends and localize the output accordingly.

Specification

Adding an optional clientContext object inside CallToolRequest (next to params). This groups related metadata fields cleanly, allows future extension, and keeps tool-call context self-contained.

Functional

• The client SHOULD send one or more of the following fields:
  • timezone: IANA time zone identifier (e.g., "Europe/Vienna") representing the user’s current time zone.
  • currentTimestamp: ISO 8601 timestamp indicating the current date/time from the user’s environment (e.g., "2025-11-12T14:23:00+01:00").
  • locale: A locale identifier (e.g., "en-US", "de-AT") representing the user’s regional preferences following IETF language tag.
• The server MUST be able to read these fields when present, and MUST use them for time interpretation and response formatting.
• The fields are optional; absence means the server falls back to default semantics (e.g., UTC or server default timezone, generic formatting).
• If multiple fields are provided, the server may use them in combination (e.g., apply timezone together with currentTimestamp, or format using locale).
• Values SHOULD reflect the user’s context at the time of the request (or at least approximate it).

Non-Functional

• The solution MUST be transport-agnostic (work over JSON-RPC, STDIO, HTTP, etc).
• The change MUST maintain backward compatibility: clients/servers not aware of the new fields continue to interoperate.
• The design MUST avoid requiring LLM inference of timezone/locale and rely on explicit metadata.
• The overhead on clients and servers SHOULD be minimal (optional fields, simple types).

Schema Update

Extend the CallToolRequest schema to include the following under params:

"CallToolRequest": {
  "description": "Used by the client to invoke a tool provided by the server.",
  "type": "object",
  "properties": {
    "method": {
      "const": "tools/call",
      "type": "string"
    },
    "params": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": { "type": "string" },
        "arguments": {
          "type": "object",
          "additionalProperties": {}
        }
      }
    },
    "clientContext": {
      "type": "object",
      "description": "Optional metadata about the client/user environment",
      "properties": {
        "timezone": {
          "type": "string",
          "description": "IANA time zone identifier (e.g., 'Europe/Vienna', 'America/Los_Angeles')"
        },
        "currentTimestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp representing current date/time in user's environment (e.g., '2025-11-12T14:23:00+01:00')"
        },
        "locale": {
          "type": "string",
          "description": "Locale identifier for the user’s regional formatting preferences (e.g., 'en-US', 'de-AT') following [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag)"
        },
        "userLocation": {
          "type": "object",
          "description": "Optional coarse geographic hint for the user environment.",
          "properties": {
            "city": {
              "type": "string",
              "description": "User’s city or locality (e.g., 'Vienna')."
            },
            "region": {
              "type": "string",
              "description": "User’s region/state or province (e.g., 'Vienna State', 'California')."
            },
            "country": {
              "type": "string",
              "description": "ISO 3166-1 alpha-2 country code (e.g., 'AT', 'US')."
            },
            "coordinates": {
              "type": "object",
              "description": "Optional latitude and longitude of the user’s approximate location.",
              "properties": {
                "latitude": { "type": "number" },
                "longitude": { "type": "number" }
              }
            }
          }
        }
      }
    }
  },
  "required": ["method", "params"]
}

Semantics

• When clientContext.timezone is provided, the server MUST interpret relative date/time expressions in that time zone.
• When clientContext.currentTimestamp is provided, the server MUST treat that timestamp as “now” from the user’s perspective.
• When clientContext.locale is provided, the server SHOULD format responses (dates, numbers, currency) according to that locale.
• If both timezone and currentTimestamp are provided, the server may validate or use them jointly (e.g., ensure the timestamp falls in the timezone).
• If none are provided, the server falls back to default behaviour (e.g., UTC, server locale).
• The client SHOULD to update or provide new clientContext values if the user’s environment changes mid-session (e.g., moving zones, switching locale).

Examples

Example 1 — Timezone + locale

{
  "jsonrpc": "2.0",
  "id": 101,
  "method": "tools/call",
  "params": {
    "name": "query_sales",
    "arguments": {
      "query": "sales this month"
    }
  },
  "clientContext": {
    "timezone": "Europe/Vienna",
    "locale": "de-AT"
  }
}

Example 2 — Timestamp only

{
  "jsonrpc": "2.0",
  "id": 102,
  "method": "tools/call",
  "params": {
    "name": "query_tickets",
    "arguments": {
      "query": "tickets submitted as of now"
    }
  },
  "clientContext": {
    "currentTimestamp": "2025-11-12T14:23:00+01:00"
  }
}

Example 3 — Full context

{
  "jsonrpc": "2.0",
  "id": 103,
  "method": "tools/call",
  "params": {
    "name": "query_activity",
    "arguments": {
      "query": "user logins in the last week"
    }
  },
  "clientContext": {
    "timezone": "America/Los_Angeles",
    "currentTimestamp": "2025-11-12T06:23:00-08:00",
    "locale": "en-US",
    "userLocation": {
      "city": "Los Angeles",
      "region": "California",
      "country": "US",
      "coordinates": {
        "latitude": 34.0522,
        "longitude": -118.2437
      }
    }
  }
}

Rationale

This proposal embeds a clientContext object with timezone, currentTimestamp, and locale alongside params in each CallToolRequest. By doing this at the tool-call level rather than only at session initialization:

• The server receives the exact moment of invocation (currentTimestamp) which session-level context cannot reliably provide (making "as of now" queries deterministic).
• While timezone and locale might be reasonably stable at session start, the timestamp changes for every invocation and must be current.
• Placing the fields inside params risks conflating tool arguments with context metadata — this may cause an LLM to inadvertently fill or modify them, leading to nondeterministic behaviour.
• The chosen design keeps context metadata separate from the tool’s functional arguments, supports per-call accuracy, and remains backward-compatible (since the object is optional).

Backward Compatibility

• The addition is fully backward-compatible: clients may omit clientContext and servers should continue to operate as before.
• Servers that do not yet understand clientContext can ignore it and apply existing time/locale semantics.
• Clients can adopt the new fields gradually without affecting interoperability with legacy implementations.