diff --git a/contents/docs/mcp-analytics/installation/python.mdx b/contents/docs/mcp-analytics/installation/python.mdx index b01dda023745..db5740b46fc9 100644 --- a/contents/docs/mcp-analytics/installation/python.mdx +++ b/contents/docs/mcp-analytics/installation/python.mdx @@ -116,6 +116,20 @@ from posthog.mcp import PostHogMcpStatelessSessionMiddleware app.add_middleware(PostHogMcpStatelessSessionMiddleware) ``` +### Resolve tool arguments on fresh low-level servers + +A fresh low-level `Server` has not served `tools/list`. A strict tool can reject the `context`, `llm_model`, or `conversation_id` arguments that PostHog added. + +Use `resolve_original_tool` to return the original tool descriptor from your registry. The callback must return the descriptor from before PostHog adds its arguments: + +```python +instrument(server, posthog, MCPAnalyticsOptions( + resolve_original_tool=lambda tool_name: tools_by_name.get(tool_name), +)) +``` + +The SDK removes only PostHog-owned arguments. A listing served on the same server instance has priority over this callback. + ## Configuration Pass options as `MCPAnalyticsOptions`: @@ -143,6 +157,7 @@ instrument(server, posthog, MCPAnalyticsOptions( | `before_send` | – | `(event) -> event \| None`. Change or drop each event before it's sent. See [Privacy](/docs/mcp-analytics/privacy). | | `event_properties` | – | `(request, extra) -> dict`. Adds [properties](/docs/mcp-analytics/custom-events) to every event. | | `server_build` | – | An immutable build ID, such as a Git SHA, sent as `$mcp_server_build`. 1 to 256 characters. | +| `resolve_original_tool` | – | `(tool_name) -> tool \| None`. Resolves argument ownership on a fresh low-level server. See [Resolve tool arguments on fresh low-level servers](#resolve-tool-arguments-on-fresh-low-level-servers). | | `logger` | no-op | `(message: str) -> None`. A stdio-safe sink for SDK warnings. | On raw low-level servers and standalone FastMCP, the SDK advertises the injected `context` and `llm_model` arguments as optional, not required. On standalone FastMCP with `mcp` 1.x, middleware that overrides tool listing or dispatch turns off `llm_model` injection. Model capture from client metadata still works. diff --git a/contents/docs/mcp-analytics/installation/typescript.mdx b/contents/docs/mcp-analytics/installation/typescript.mdx index 1d6b455d41b5..0fdf381c4d80 100644 --- a/contents/docs/mcp-analytics/installation/typescript.mdx +++ b/contents/docs/mcp-analytics/installation/typescript.mdx @@ -232,6 +232,23 @@ if (body?.method === "initialize" && !req.headers[MCP_SESSION_HEADER]) { } ``` +### Resolve tool arguments on fresh low-level servers + +A fresh low-level `Server` has not served `tools/list`, so it does not know which `context` and `llm_model` arguments the SDK added. A strict input schema can reject these arguments before the tool runs. + +Use `resolveOriginalTool` to return each tool's original input schema from your registry. The callback must return the schema from before PostHog adds its arguments: + +```ts +instrument(server, posthog, { + resolveOriginalTool: (toolName) => { + const tool = toolsByName.get(toolName) + return tool ? { inputSchema: tool.inputSchema } : undefined + }, +}) +``` + +The SDK strips only arguments that it added. It reads a Zod schema as the MCP SDK advertises it. If your server advertises a custom JSON Schema, return that schema instead. + ## Configuration `instrument(server, posthog, options?)` takes these options: @@ -251,6 +268,7 @@ if (body?.method === "initialize" && !req.headers[MCP_SESSION_HEADER]) { | `serverBuild` | – | An immutable build ID, such as a Git SHA, sent as `$mcp_server_build`. 1 to 256 characters. | | `shouldRecordInputKey` | declared names | Decides which argument names `$mcp_input_keys` records. Other names become one `[redacted]` entry. | | `resolveInputAliases` | – | `(toolName) => aliases`. Lists alternative argument names, recorded as `$mcp_input_aliases_used`. | +| `resolveOriginalTool` | – | `(toolName) => { inputSchema } \| undefined`. Resolves input ownership on a fresh low-level server. See [Resolve tool arguments on fresh low-level servers](#resolve-tool-arguments-on-fresh-low-level-servers). | | `logger` | no-op | `(message) => void`. A stdio-safe sink for SDK warnings. | ## Custom dispatchers