context gsc refresh

context_gsc_refresh Refresh GSC rows with read-only webmasters.readonly access. Limit each run to 12 Search Analytics calls per property and 50 total, including availability probes, reports and retries. Fresh cached requests spend no API calls. A quota refusal returns quota_exceeded with a 15-minute hint and at most one retry within the remaining call budget. Read the token from the host environment at call time. Append fact rows and read the newest answer.

Repository-local stdio MCP only. This tool is absent from hosted MCP and HTTP. It can write local context files or fetch bounded public context.

Setup and request

Start the local context host with an explicit repository root. Paths are restricted to that root, including symlink resolution.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "context_gsc_refresh",
    "arguments": {}
  }
}

Input fields

Field	Type	Presence	Meaning and constraints
`properties`	array	Optional	The properties value; allowed values and bounds are specified in this schema. minItems: 1; maxItems: 10
`dataState`	string	Optional	The data state value; allowed values and bounds are specified in this schema. values: “final”, “all”

Returned result

Captured from a local fixture repository without external credentials.

{
  "started_at": "2026-09-14T01:53:21.185Z",
  "state": "manual_only",
  "properties": [],
  "rows_written": 0,
  "markers_written": 0,
  "calls": {
    "search_analytics": 0,
    "list_sites": 0,
    "budget_per_property": 12,
    "hard_cap_per_run": 50
  },
  "served_from_repo": 0,
  "states": [],
  "quota": null,
  "notes": [
    "no Google connection configured; manual.md is the context and handoff rows (if any) are unaffected"
  ]
}

started_at (string, required): Run start timestamp.
state (string, required): Run state: ok, manual_only, not_authorized, revoked, or quota_exceeded.
properties (array, required): Requested property outcomes.
rows_written (integer, required): Fact rows appended this run. minimum: 0
markers_written (integer, required): Window markers appended this run. minimum: 0
calls (object, required): Call accounting. additional fields rejected
served_from_repo (integer, required): Fresh request groups read from repository cache. minimum: 0
states (array, required): Collected window/property states; inspect alongside the overall state.
quota (object / null, required): Quota refusal details.
notes (array, required): Run limits and manual-context notes.

All fields and nested objects

Field	Type	Presence	Meaning and constraints
`started_at`	string	Required	Run start timestamp.
`state`	string	Required	Run state: ok, manual_only, not_authorized, revoked, or quota_exceeded.
`properties`	array	Required	Requested property outcomes.
`properties[].siteUrl`	string	Required	Property identifier.
`properties[].permissionLevel`	string / null	Optional	Observed permission label; current successful refresh records leave this null.
`properties[].state`	string	Required	Property-level outcome; inspect windows for detailed partial coverage.
`properties[].rows_written`	integer	Optional	Fact rows appended for this property. minimum: 0
`properties[].markers_written`	integer	Optional	Window markers appended. minimum: 0
`properties[].windows`	array	Optional	Per-window outcomes.
`properties[].windows[].window`	object	Required	Selected date window. additional fields rejected
`properties[].windows[].window.start`	string	Required	Calendar date in YYYY-MM-DD form.
`properties[].windows[].window.end`	string	Required	Calendar date in YYYY-MM-DD form.
`properties[].windows[].window.days`	integer	Optional	Inclusive day count. minimum: 0
`properties[].windows[].grouping`	array	Optional	Requested dimensions.
`properties[].windows[].state`	string	Required	Window outcome: ok, served_from_repo, empty_site, truncated_top_rows, incomplete_window, budget_reached, quota_exceeded, revoked, or window_before_available_data.
`properties[].windows[].budget`	object	Optional	Budget reached before this request. additional fields rejected
`properties[].windows[].budget.per_property`	integer	Required	Per-property request ceiling. minimum: 0
`properties[].windows[].budget.hard_cap`	integer	Required	Whole-run request ceiling. minimum: 0
`properties[].windows[].hint_minutes`	integer	Optional	Quota retry hint. minimum: 0
`properties[].windows[].partial`	boolean	Optional	Authorization changed after earlier writes.
`properties[].windows[].rows_returned`	integer	Optional	Rows returned for the window. minimum: 0
`properties[].windows[].truncated`	boolean	Optional	Returned rows hit the cap.
`properties[].windows[].first_incomplete_date`	string / null	Optional	Calendar date in YYYY-MM-DD form.
`properties[].calls`	integer	Optional	Search Analytics calls including probes and retries. minimum: 0
`properties[].availability`	object	Optional	Availability probe record. additional fields rejected
`properties[].availability.property`	string	Optional	Property identifier on a newly probed result.
`properties[].availability.first_available_date`	string / null	Required	Calendar date in YYYY-MM-DD form.
`properties[].availability.probed_at`	string	Required	Probe timestamp.
`properties[].availability.probes_used`	integer	Required	Probe calls used. minimum: 0
`properties[].availability.basis`	string	Required	Evidence or budget reason for the availability floor.
`properties[].availability.cached`	boolean	Optional	Whether the saved probe was reused.
`rows_written`	integer	Required	Fact rows appended this run. minimum: 0
`markers_written`	integer	Required	Window markers appended this run. minimum: 0
`calls`	object	Required	Call accounting. additional fields rejected
`calls.search_analytics`	integer	Required	Search Analytics calls including probes and retries. minimum: 0
`calls.list_sites`	integer	Required	Property-list calls. minimum: 0
`calls.budget_per_property`	integer	Required	Search Analytics ceiling per property. minimum: 0
`calls.hard_cap_per_run`	integer	Required	Search Analytics ceiling per run. minimum: 0
`served_from_repo`	integer	Required	Fresh request groups read from repository cache. minimum: 0
`states`	array	Required	Collected window/property states; inspect alongside the overall state.
`quota`	object / null	Required	Quota refusal details.
`quota.hint_minutes`	integer	Required	Quota wait hint in minutes. minimum: 0
`quota.retries_used`	integer	Required	Retries recorded at the quota refusal. minimum: 0
`notes`	array	Required	Run limits and manual-context notes.

Inspect property and window outcomes even when the overall state is ok. Authentication loss preserves earlier saved rows. No configured token returns manual_only with zero Search Analytics calls. Download result schema.

Result and recovery

The host returns JSON in both structuredContent and text content. The local context reference describes each result, file ownership and recovery. Start/end dates must be supplied together. Thrown input or file failures return isError: true. Missing manual/profile files and unresolved citations also flag an error. Inspect returned connection states separately: revoked or unavailable access can be result data. Manual-only configuration is valid. See local context, CLI context commands and schema conventions.

Overview

MCP, CLI and API commands

CLI client

HTTP and events

Optional local workflows

Setup and request

Input fields

Returned result

Result and recovery

​Setup and request

​Input fields

​Returned result

​Result and recovery

Setup and request

Input fields

Returned result

Result and recovery