MCP telemetry

The CodeCharter MCP server can send anonymised usage telemetry to the portal so you can see how your team uses CodeCharter. Telemetry is strictly opt-in and off by default. Nothing leaves your machine until you turn it on through one of the three activation paths below. When you do, the server tells you in plain text on startup, and you can turn it back off at any time.

The data is designed so that it never carries your source code, your file structure, or anyone's identity. The collected fields are a fixed allowlist; the sensitive fields are not "filtered out" at runtime, they are structurally absent from the payload type, so they cannot be sent even by accident.

Enabling telemetry

Telemetry activates when any one of the following is present. The three paths are OR-combined, so a single one is enough. When more than one path is present, they are checked in a fixed priority order — CLI flag, then environment variable, then config file — and the first one that enables telemetry also decides the endpoint. In particular, while CODECHARTER_TELEMETRY=1 is set, the default endpoint is used and a custom telemetry.endpoint in codecharter.config.json is ignored.

1. Config file

Add a codecharter.config.json in the working directory where you launch the MCP server:

{
  "telemetry": {
    "enabled": true,
    "endpoint": "https://codecharter.tools"
  }
}

The endpoint key is optional and defaults to https://codecharter.tools.

A malformed codecharter.config.json (invalid JSON or a wrong value type) is treated as telemetry-disabled without any warning. If telemetry unexpectedly stays off, validate the file's JSON first.

2. Environment variable

Set CODECHARTER_TELEMETRY=1 in the environment before launching codecharter mcp. Only the value 1 enables telemetry; any other value (including 0) has no effect. This variable can only enable telemetry — it cannot disable it. Telemetry is opt-in and off by default regardless of this variable's presence.

CODECHARTER_TELEMETRY=1 codecharter mcp

3. CLI flag

Pass --telemetry to codecharter mcp. An optional --telemetry-endpoint overrides the ingestion URL:

codecharter mcp --telemetry
codecharter mcp --telemetry --telemetry-endpoint https://codecharter.tools

First-launch notice

When telemetry is active, the MCP server writes a single line to stderr on startup so the activation is never silent:

[codecharter] Telemetry enabled. Data goes to <endpoint>. Overview: /docs/en/cli/telemetry

To turn telemetry off again, remove every activation path that is currently enabling it: drop the --telemetry flag, unset CODECHARTER_TELEMETRY, and set "enabled": false in (or remove) the config file. Because the paths are OR-combined, setting "enabled": false in the config file alone does not override a still-present flag or environment variable. Once no path enables telemetry, no further events are sent from the next server start onward.

What is collected

Every tool call produces one event. The payload contains only the fields in the allowlist below.

Field	Description
tool_name	Name of the MCP tool that was called (for example analyze_file).
latency_bucket	Call latency rounded down to the next lower 50 ms step (for example, 74 ms is reported as 50). The exact value is never transmitted.
is_success	true when the call completed successfully; false when the tool returned an error result or threw an unhandled exception.
workspace_id	Reserved field. The MCP server never transmits your repository path, not even hashed: it always sends a fixed placeholder hash here.
finding_summaries	Reserved field of { rule_id, severity, count } entries. The MCP server always sends an empty list; no per-rule finding counts leave your machine from MCP tool calls.
license_id	License nonce GUID used for account attribution. Absent when no license is loaded.
client_instance_id	Stable per-installation GUID, randomly generated and stored locally at the first telemetry-enabled server start. Lets the portal slice usage per workstation without identifying anyone. See Resetting your client instance id.
code_guard_version	CodeCharter CLI version string.
dot_net_version	.NET runtime version string (for example 9.0.1).
os_family	Operating-system family: win, mac, or linux.
occurred_at_utc	UTC timestamp when the event was recorded.

What is never collected

The following fields are explicitly excluded. They are structurally absent from the telemetry payload type, so they cannot be added without a separate, tracked change. This is the core of the data-protection design: your intellectual property and your developers' identities stay on your machine.

Blocked field	Reason
Source code content	Contains your intellectual property.
File paths, including in findings	Reveals directory layout and project structure.
Diff contents	Contains your intellectual property.
Git author name and email	Personal data under GDPR Article 4.
Custom rule DSL text	Contains your conventions and business logic.
File names	Reveals project structure.
Class names	Reveals design decisions.
Method names	Reveals design decisions.
Finding message text	May contain code snippets.

What you get in return: the Insights page

With telemetry enabled, the portal aggregates the events under your license and renders them on the Insights page. The page is available to every signed-in account and is most useful for team leads who want to understand how CodeCharter is used across the team. You can switch each view between a 7-day, 30-day, and 90-day window. Until the first events arrive, the page shows an empty state with a link back to this documentation, so do not expect data immediately after enabling telemetry.

The Insights page shows:

• Tool-call volume per tool: how often each MCP tool (analyze_file, analyze_solution, dry_run_rule, and the others) was called over the selected window.
• Latency percentiles per tool: p50, p95, and p99 call latency per tool, so slow tools and regressions stand out.
• Top rules by finding frequency: which rules produce the most findings, a good signal for where your codebase or your team needs attention. MCP events carry no finding counts, so this view fills up only from codecharter analyze --telemetry runs.
• Success and error rate over time: the share of successful versus failed calls per day across the window.
• Per-developer breakdown: a row per client_instance_id, showing call volume, success rate, and the top rules each workstation triggers most often. The top-rules column likewise stays empty for pure MCP usage and is populated by codecharter analyze --telemetry runs. This answers questions like which workstation hits which rule most frequently, without ever identifying a person, because the id is a random local GUID.

Transport

Events are batched in memory and POSTed as a JSON array to {endpoint}/api/v1/telemetry/events over HTTPS. The batch flushes every 30 seconds or once 50 events have accumulated, whichever comes first. Shutting the server down flushes the remaining buffer. Telemetry is fail-open: transport errors are swallowed and logged to stderr, so a failed send never breaks the server's normal operation. There is no retry queue; a failed POST is dropped.

Uploads are authenticated with your license: it is sent as a bearer credential on every telemetry POST, and the portal rejects unauthenticated uploads. Events therefore only appear on the Insights page when a valid license is loaded.

Retention

Telemetry events are retained for 60 days and then deleted automatically. Aggregated evaluations without any personal reference may be kept beyond that.

Resetting your client instance id

The client_instance_id is stored as plain text in a single file:

• Windows: %LOCALAPPDATA%\CodeCharter\client-instance-id
• Linux and macOS: $XDG_DATA_HOME/codecharter/client-instance-id, with the fallback ~/.codecharter/client-instance-id when XDG_DATA_HOME is unset.

Delete the file to reset the id. The next telemetry-enabled MCP launch generates and persists a fresh random GUID. Past events keyed to the old id stay on the portal until the 60-day retention window expires; no new events reference the old id once it has been replaced.

Data protection and deletion requests

The payload contains no personal data as defined by GDPR Article 4. The workspace id is a fixed placeholder hash, the license nonce is a random UUID that does not map to a name or email outside the billing system, and the client instance id is a random local GUID, not derived from hardware or any personal attribute. The full GDPR disclosure is on the Privacy and GDPR page.

To request deletion of all events associated with your license, send an email to [email protected] with the subject line "Telemetry deletion request" and your license attached. You can download your license file (codecharter.license) from the portal Downloads page.

Related

• Privacy and GDPR covers the legal basis, recipients, and your rights.
• MCP rule authoring covers the MCP tools that produce the telemetry events.
• Insights page is where the aggregated data lands.