Documentation
¶
Overview ¶
Package posthogmcp builds and enqueues canonical PostHog analytics events for Model Context Protocol activity without depending on a particular MCP framework.
Applications own the PostHog client lifecycle and pass completed tool calls to Analytics. Tool parameters, responses, intent, and error messages are sanitized and bounded before they are queued. Parameter or response JSON exceeding 1 MiB after media redaction is replaced with an omission marker.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Analytics ¶
type Analytics struct {
// contains filtered or unexported fields
}
Analytics constructs and enqueues canonical PostHog MCP analytics events. It does not own the lifecycle of the PostHog client.
func New ¶
func New(client posthog.EnqueueClient, opts ...Option) *Analytics
New creates an MCP analytics recorder using client.
func (*Analytics) CaptureToolCall ¶
CaptureToolCall validates, transforms, and enqueues one completed MCP tool call. When exception autocapture is enabled, all messages are built before either is enqueued. Enqueue failures are joined after every configured message has been attempted.
A posthog.RequestContext attached to ctx supplies the distinct and session IDs the call leaves empty, and its properties sit under call.Properties. They go through the same reserved-key and sanitization rules as the call's own.
Example ¶
package main
import (
"context"
"log"
"time"
posthog "github.com/posthog/posthog-go"
"github.com/posthog/posthog-go/posthogmcp"
)
func main() {
client := posthog.New("phc_project_key")
defer client.Close()
analytics := posthogmcp.New(client)
err := analytics.CaptureToolCall(context.Background(), posthogmcp.ToolCall{
ToolName: "search_docs",
DistinctID: "user_123",
Duration: 42 * time.Millisecond,
})
if err != nil {
log.Printf("capture MCP analytics: %v", err)
}
}
Output:
type IntentSource ¶
type IntentSource string
IntentSource identifies how an MCP tool-call intent was obtained.
const ( // IntentSourceContextParameter means the MCP client supplied the intent in a // tool context parameter. IntentSourceContextParameter IntentSource = "context_parameter" // IntentSourceInferred means the host application inferred the intent. IntentSourceInferred IntentSource = "inferred" )
type Option ¶
type Option func(*config)
Option configures Analytics.
func WithExceptionAutocapture ¶
WithExceptionAutocapture controls whether failed tool calls also enqueue a PostHog exception. It is enabled by default.
type ToolCall ¶
type ToolCall struct {
ToolName string
ToolDescription string
ToolCategory string
DistinctID string
SessionID string
Groups posthog.Groups
SetProperties posthog.Properties
ServerName string
ServerVersion string
ClientName string
ClientVersion string
ProtocolVersion string
// Intent is the agent's stated reason for the call. When it arrives as a
// tool argument, remove that argument from Parameters: Parameters only has
// credentials redacted, while Intent also has personal data redacted.
Intent string
IntentSource IntentSource
// Parameters is captured as $mcp_parameters as given, like the manual
// capture APIs in the Python and TypeScript SDKs. Automatic
// instrumentation passes the JSON-RPC request here, as
// {"request": {"method": "tools/call", "params": {"name": ..., "arguments": ...}}}.
Parameters any
Response any
Duration time.Duration
// IsError marks a failed call that has no Go error, such as an MCP result
// with isError set. A non-nil Error implies IsError.
IsError bool
// Error is the failure, if any. When set, it is also captured as a
// $exception unless exception autocapture is disabled.
Error error
ErrorType string
// Properties adds custom event metadata. $mcp_* and identity control keys
// are reserved; use the corresponding ToolCall fields instead.
Properties posthog.Properties
Timestamp time.Time
}
ToolCall describes one completed MCP tool invocation.
Source Files