Skip to content

feat(mcp-analytics): define how SDKs derive $mcp_error_status - #212

Merged
lucasheriques merged 2 commits into
mainfrom
lucas/mcp-error-status
Nov 11, 2026
Merged

lucasheriques merged 2 commits into
mainfrom
lucas/mcp-error-status

Conversation

@lucasheriques

@lucasheriques lucasheriques commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Why

MCP Analytics groups failed tool calls by $mcp_error_status, but only PostHog's own MCP server sets it, so every failure from a server using the SDKs lands in "unknown". The spec lists the property as a MAY with no derivation, so two SDKs could put different numbers on the same failure. Rootly asked for it in PostHog/posthog-python#1223.

What changes

Failure capture. $mcp_error_status stays a MAY. An SDK that derives it from a thrown error follows one rule:

  • Walk the cause chain from the thrown error inward, each error once, at most 50 errors. Python follows __cause__, else __context__ unless __suppress_context__. JavaScript follows cause.
  • On each error read status_code, statusCode, status, first on the error, then on its response.
  • The first integer from 100 to 599 wins. A boolean or numeric string is not one.
  • The outermost error with a status wins. No status means no property. An explicit caller value wins.

One new scenario. The Property reference row now says integer, 100 to 599.

PostHog's own server reads status off its API error found through cause, so its values already fit the rule.

Implementations

SDK Status
posthog-python posthog.mcp PostHog/posthog-python#1229
posthog-js @posthog/mcp PostHog/posthog-js#5671
posthog-go, posthog-ruby, posthog-rs not yet (tasks 4.2)

Validation

openspec validate mcp-analytics --type spec --strict reports no errors (existing length warnings only). The acceptance feature is unchanged until the harness has a step binding (tasks 4.3).

$mcp_error_status was a MAY with no derivation, so only PostHog's own server set it and
every external SDK failure grouped as "unknown" in the failure views. Pin one rule: walk
the cause chain from the thrown error inward and take the first integer 100-599 from
status_code, statusCode or status on the error or its response. A caller's explicit value
wins. Stays a MAY; posthog-python and posthog-js implement it next (posthog-python#1223).

Tested: openspec validate mcp-analytics --type spec --strict (no errors; existing
length warnings only).
Pre-PR review showed a chain built on read never ends. 50 matches the $exception_list
bound the SDKs already apply.
@lucasheriques
lucasheriques merged commit 4d19cd8 into main Nov 11, 2026
11 checks passed
@lucasheriques
lucasheriques deleted the lucas/mcp-error-status branch November 11, 2026 20:35
lucasheriques added a commit that referenced this pull request Nov 12, 2026
What: resolve the three conflicts in openspec/specs/mcp-analytics/spec.md and
resync the archived delta with the merged requirement.
- Configuration table: keep the error message capture row, drop the payload
  personal data row (main removed that option).
- Failure capture: keep the option-off paragraph, reworded because Payload
  privacy no longer applies the personal data pass to error messages; take
  main's $mcp_error_status derivation rules.
- Scenarios: keep both the option-off scenario and main's HTTP status one.
- Archived change: MODIFIED Failure capture delta now mirrors the merged
  requirement; proposal and design no longer claim a personal data pass on
  error messages.

Why: #192 conflicted with main after #212 and the payload personal data removal.
#184's content is not part of this PR and is not depended on.

Tested: openspec validate --specs --strict --no-interactive with
@fission-ai/openspec@1.4.1 (CI's version): 69 passed, 0 failed. Unarchived
changes check: none outside openspec/changes/archive.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants