Skip to content

Commit dd7577b

Browse files
feat(mcp): set $mcp_error_status from the raised exception's cause chain (#1229)
* feat(mcp): set $mcp_error_status from the raised exception's cause chain MCP Analytics groups failed calls by $mcp_error_status, but only PostHog's own server set it, so every posthog.mcp failure landed in "unknown". Rootly asked for it in #1223. Walk the cause chain inward (__cause__, else __context__ unless suppressed) and take the first int 100-599 from status_code, statusCode or status on the exception or its response, per the sdk-specs Failure capture rule. A caller's properties still win. Tested: pytest posthog/test/mcp (720 passed, 11 skipped); new parameterized test_error_status.py covers chain shapes and rejected values; FastMCP end-to-end row raises httpx.HTTPStatusError(503) under mask_error_details=True. * fix(mcp): follow __cause__ whenever set, and cap the status walk at 50 links Pre-PR adversarial review found two gaps against the sdk-specs rule: a __cause__ left with __suppress_context__ False was skipped for __context__, and a chain whose links are built on read never ended. Walk the chain a traceback prints, capped at 50 links like $exception_list. Tested: pytest posthog/test/mcp (724 passed, 11 skipped); mypy baseline clean. * fix(mcp): type the status walk's seen set, and record ERROR_STATUS in the API snapshot CI on 68b8974 failed Mypy (var-annotated on `seen` in _exceptions.py) and the Public API snapshot check (the new PostHogMCPAnalyticsProperty.ERROR_STATUS constant), which PostHog Review also flagged. Tested: mypy | mypy-baseline filter clean; check_public_api.py up to date; pytest posthog/test/mcp 725 / 606 / 716 passed on fastmcp 3.2 + mcp 1.30, 4.1.8 + mcp 2.3, 2.14.7 + mcp 1.30.
1 parent 0139861 commit dd7577b

11 files changed

Lines changed: 232 additions & 7 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
pypi/posthog: minor
3+
---
4+
5+
`posthog.mcp`: a failed tool call now sets `$mcp_error_status` to the HTTP status behind it, read from the raised exception or its cause chain (`status_code`, `statusCode` or `status`, on the exception or its `response`, as `httpx.HTTPStatusError` and `requests.HTTPError` carry it). Failures from an upstream API now group by status in MCP Analytics instead of landing in "unknown".

‎posthog/mcp/_capture.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ def capture_event(
6969
"is_error": event_input.get("is_error"),
7070
"error": event_input.get("error"),
7171
"error_type": event_input.get("error_type"),
72+
"error_status": event_input.get("error_status"),
7273
"conversation_id": event_input.get("conversation_id"),
7374
"properties": event_input.get("properties"),
7475
}

‎posthog/mcp/_exceptions.py‎

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
from __future__ import annotations
1212

13-
from typing import Any, List
13+
from typing import Any, Iterator, List, Optional, Set
1414

1515
from posthog.exception_utils import exceptions_from_error_tuple
1616

@@ -38,6 +38,53 @@ def capture_exception(error: Any) -> ErrorProperties:
3838
return _from_message(_safe_str(error))
3939

4040

41+
_STATUS_ATTRIBUTES = ("status_code", "statusCode", "status")
42+
_MAX_CHAIN_LINKS = 50
43+
44+
45+
def http_status(error: Any) -> Optional[int]:
46+
"""The HTTP status behind a failure, for ``$mcp_error_status``: the first
47+
one found walking the raised exception's cause chain inward, so a status the
48+
tool raised itself beats the one on the error it wrapped (httpx and requests
49+
keep theirs on ``response.status_code``)."""
50+
for link in _cause_chain(error):
51+
for holder in (link, _attribute(link, "response")):
52+
for name in _STATUS_ATTRIBUTES:
53+
status = _attribute(holder, name)
54+
if (
55+
isinstance(status, int)
56+
and not isinstance(status, bool)
57+
and 100 <= status <= 599
58+
):
59+
return int(status)
60+
return None
61+
62+
63+
def _cause_chain(error: Any) -> Iterator[BaseException]:
64+
"""The chain a traceback prints, capped like ``$exception_list``."""
65+
seen: Set[int] = set()
66+
link = error
67+
while (
68+
isinstance(link, BaseException)
69+
and id(link) not in seen
70+
and len(seen) < _MAX_CHAIN_LINKS
71+
):
72+
seen.add(id(link))
73+
yield link
74+
if link.__cause__ is not None:
75+
link = link.__cause__
76+
else:
77+
link = None if link.__suppress_context__ else link.__context__
78+
79+
80+
def _attribute(value: Any, name: str) -> Any:
81+
# A third-party property can raise anything; a failed probe must not drop the event.
82+
try:
83+
return getattr(value, name, None)
84+
except Exception:
85+
return None
86+
87+
4188
def _from_message(message: str) -> ErrorProperties:
4289
return {
4390
"$exception_list": [

‎posthog/mcp/_instrumentation.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
resolve_conversation_id,
3131
)
3232
from ._event_types import MCPAnalyticsEventType
33-
from ._exceptions import capture_exception
33+
from ._exceptions import capture_exception, http_status
3434
from .feedback import (
3535
build_feedback_event_properties,
3636
build_feedback_intent,
@@ -826,6 +826,7 @@ async def record_tool_call(
826826
if error is not None:
827827
event["is_error"] = True
828828
event["error"] = capture_exception(error)
829+
event["error_status"] = http_status(error)
829830

830831
props = await resolve_event_properties(data, request, extra)
831832
input_aliases = None

‎posthog/mcp/_posthog_events.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,8 @@ def _add_error_details(event: Event, properties: Dict[str, Any]) -> None:
252252
message = first.get("value")
253253
if message:
254254
properties[_P.ERROR_MESSAGE] = message
255+
if event.get("error_status") is not None:
256+
properties[_P.ERROR_STATUS] = event["error_status"]
255257

256258

257259
def _add_custom_properties(event: Event, properties: Dict[str, Any]) -> None:

‎posthog/mcp/constants.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ class PostHogMCPAnalyticsProperty:
6868
CONVERSATION_ID = "$mcp_conversation_id"
6969
DURATION_MS = "$mcp_duration_ms"
7070
ERROR_MESSAGE = "$mcp_error_message"
71+
ERROR_STATUS = "$mcp_error_status"
7172
ERROR_TYPE = "$mcp_error_type"
7273
FEEDBACK_DETAILS = "$mcp_feedback_details"
7374
FEEDBACK_FRICTION_POINTS = "$mcp_feedback_friction_points"

‎posthog/mcp/posthog_mcp.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
resolve_conversation_id,
3434
)
3535
from ._event_types import MCPAnalyticsEventType
36-
from ._exceptions import capture_exception
36+
from ._exceptions import capture_exception, http_status
3737
from ._instrumentation import (
3838
VIRTUAL_TOOL_FEEDBACK,
3939
VIRTUAL_TOOL_MISSING_CAPABILITY,
@@ -242,6 +242,7 @@ def capture_tool_call(
242242
event["error"] = capture_exception(
243243
error if error is not None else f"Tool {tool_name} returned an error"
244244
)
245+
event["error_status"] = http_status(error)
245246
self._emit(event)
246247

247248
def capture_initialize(

‎posthog/mcp/types.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@
6363
# plain dict (constructed and read with ``.get()`` throughout) to mirror the TS
6464
# plain-object pipeline. Snake_case keys map to the ``$mcp_*`` wire keys in
6565
# ``posthog_events``. Known keys: client_name, client_version, conversation_id,
66-
# duration, error, error_type, event_name, event_type, groups, id, identify_actor_data,
66+
# duration, error, error_status, error_type, event_name, event_type, groups, id, identify_actor_data,
6767
# identify_actor_given_id, is_error, listed_tool_names, parameters, properties,
6868
# resource_name, response, server_name, server_version, session_id, timestamp,
6969
# tool_category, tool_description, user_intent, user_intent_source, llm_model,
Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
"""``$mcp_error_status``: the HTTP status behind a failed call, read off the
2+
raised exception's cause chain (posthog-python#1223, sdk-specs mcp-analytics
3+
"Failure capture")."""
4+
5+
from http import HTTPStatus
6+
from types import SimpleNamespace
7+
8+
import httpx
9+
import pytest
10+
11+
from posthog.mcp import PostHogMCP
12+
from posthog.mcp.constants import PostHogMCPAnalyticsProperty as P
13+
from posthog.test.mcp._helpers import events_named, flush_background
14+
15+
16+
class Failure(Exception):
17+
def __init__(self, message="failed", **attributes):
18+
super().__init__(message)
19+
for name, value in attributes.items():
20+
setattr(self, name, value)
21+
22+
23+
def _http_status_error(status):
24+
request = httpx.Request("GET", "https://api.example.com/invoices/1")
25+
response = httpx.Response(status, request=request)
26+
return httpx.HTTPStatusError(
27+
f"{status} from upstream", request=request, response=response
28+
)
29+
30+
31+
def _raised_from(outer, inner):
32+
try:
33+
try:
34+
raise inner
35+
except Exception as error:
36+
raise outer from error
37+
except Exception as error:
38+
return error
39+
40+
41+
def _raised_during(outer, inner):
42+
try:
43+
try:
44+
raise inner
45+
except Exception:
46+
raise outer
47+
except Exception as error:
48+
return error
49+
50+
51+
def _raised_from_none(outer, inner):
52+
try:
53+
try:
54+
raise inner
55+
except Exception:
56+
raise outer from None
57+
except Exception as error:
58+
return error
59+
60+
61+
def _cause_without_suppressed_context():
62+
error = _raised_during(RuntimeError("lookup failed"), Failure(status=500))
63+
error.__cause__ = Failure(status=404)
64+
error.__suppress_context__ = False
65+
return error
66+
67+
68+
def _chain_of(length, status):
69+
error = Failure("innermost", status=status)
70+
for _ in range(length - 1):
71+
error = _raised_from(Failure("wrapper"), error)
72+
return error
73+
74+
75+
class UnreadableResponse(Exception):
76+
@property
77+
def response(self):
78+
raise RuntimeError("response not loaded")
79+
80+
81+
def _cycle():
82+
first, second = Failure("first"), Failure("second")
83+
first.__cause__, second.__cause__ = second, first
84+
return first
85+
86+
87+
@pytest.mark.parametrize(
88+
"error, status",
89+
[
90+
(_http_status_error(503), 503),
91+
(_raised_from(RuntimeError("lookup failed"), _http_status_error(503)), 503),
92+
(_raised_during(RuntimeError("lookup failed"), _http_status_error(429)), 429),
93+
(
94+
_raised_from_none(RuntimeError("lookup failed"), _http_status_error(503)),
95+
None,
96+
),
97+
(_raised_from(Failure(status_code=404), _http_status_error(503)), 404),
98+
(Failure(status_code=502), 502),
99+
(Failure(statusCode=502), 502),
100+
(Failure(status=502), 502),
101+
(Failure(status_code=None, status=502), 502),
102+
(Failure(response=SimpleNamespace(status=502)), 502),
103+
(Failure(status="failed", response=SimpleNamespace(status_code=401)), 401),
104+
(Failure(status=HTTPStatus.BAD_GATEWAY), 502),
105+
(Failure(status_code=42), None),
106+
(Failure(status_code=600), None),
107+
(Failure(status_code=True), None),
108+
(Failure(status_code="503"), None),
109+
(Failure(status_code=503.0), None),
110+
(Failure("no status here"), None),
111+
(_cause_without_suppressed_context(), 404),
112+
(_chain_of(50, 503), 503),
113+
(_chain_of(51, 503), None),
114+
(_cycle(), None),
115+
(UnreadableResponse("failed"), None),
116+
("upstream returned 503", None),
117+
],
118+
)
119+
async def test_failed_call_carries_the_status_from_the_cause_chain(error, status):
120+
client = PostHogMCP("phc_test")
121+
captured = []
122+
client.capture = lambda event, **kw: captured.append({"event": event, **kw})
123+
124+
client.capture_tool_call("fetch_invoice", is_error=True, error=error)
125+
await flush_background()
126+
127+
[call] = events_named(captured, "$mcp_tool_call")
128+
assert call["properties"].get(P.ERROR_STATUS) == status
129+
130+
131+
async def test_explicit_status_wins_over_the_derived_one():
132+
client = PostHogMCP("phc_test")
133+
captured = []
134+
client.capture = lambda event, **kw: captured.append({"event": event, **kw})
135+
136+
client.capture_tool_call(
137+
"fetch_invoice",
138+
is_error=True,
139+
error=_http_status_error(503),
140+
properties={P.ERROR_STATUS: 418},
141+
)
142+
await flush_background()
143+
144+
[call] = events_named(captured, "$mcp_tool_call")
145+
assert call["properties"][P.ERROR_STATUS] == 418

‎posthog/test/mcp/test_fastmcp_tool_errors.py‎

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
import logging
88
import weakref
99

10+
import httpx
1011
import pytest
1112

1213
pytest.importorskip("fastmcp")
@@ -33,6 +34,14 @@ def _tool_error():
3334
raise ToolError("bad input")
3435

3536

37+
def _upstream_status():
38+
request = httpx.Request("GET", "https://api.example.com/invoices/1")
39+
try:
40+
httpx.Response(503, request=request).raise_for_status()
41+
except httpx.HTTPStatusError as exc:
42+
raise RuntimeError("invoice lookup failed") from exc
43+
44+
3645
def _tool_error_worded_like_fastmcp():
3746
try:
3847
_upstream()
@@ -41,34 +50,45 @@ def _tool_error_worded_like_fastmcp():
4150

4251

4352
@pytest.mark.parametrize(
44-
"raise_in_tool, mask_error_details, error_type, message, chain",
53+
"raise_in_tool, mask_error_details, error_type, message, chain, status",
4554
[
4655
(
4756
_chained,
4857
False,
4958
"RuntimeError",
5059
"lookup failed",
5160
["RuntimeError", "ConnectionError"],
61+
None,
5262
),
5363
(
5464
_chained,
5565
True,
5666
"RuntimeError",
5767
"lookup failed",
5868
["RuntimeError", "ConnectionError"],
69+
None,
5970
),
60-
(_tool_error, False, "ToolError", "bad input", ["ToolError"]),
71+
(_tool_error, False, "ToolError", "bad input", ["ToolError"], None),
6172
(
6273
_tool_error_worded_like_fastmcp,
6374
False,
6475
"ToolError",
6576
"Error calling tool: lookup failed",
6677
["ToolError", "ConnectionError"],
78+
None,
79+
),
80+
(
81+
_upstream_status,
82+
True,
83+
"RuntimeError",
84+
"invoice lookup failed",
85+
["RuntimeError", "HTTPStatusError"],
86+
503,
6787
),
6888
],
6989
)
7090
async def test_failed_call_carries_the_raised_exception(
71-
raise_in_tool, mask_error_details, error_type, message, chain
91+
raise_in_tool, mask_error_details, error_type, message, chain, status
7292
):
7393
server = FastMCP("example-server", mask_error_details=mask_error_details)
7494

@@ -89,6 +109,7 @@ def fail() -> str:
89109
assert call["properties"]["$mcp_is_error"] is True
90110
assert call["properties"]["$mcp_error_type"] == error_type
91111
assert call["properties"]["$mcp_error_message"] == message
112+
assert call["properties"].get("$mcp_error_status") == status
92113
[exception] = events_named(sink, "$exception")
93114
exception_list = exception["properties"]["$exception_list"]
94115
raised = [e for e in exception_list if e["type"] in chain]

0 commit comments

Comments
 (0)