agentcat

README

Getting Started · Features · Docs · Website · Open Source · Schedule a Demo

[!NOTE] AgentCat v2 introduces compatibility with the MCP Protocol "Stateless" 2026-07-28 Update and the coinciding mcp-go and official go-sdk releases that put it into effect. The stateless transition has a massive impact on analytics, as sessions were a built-in concept tying related tool calls together. AgentCat has now migrated its session tracking under guidance of the MCP core team's recommendations of using explicit handles (SEP-2567).

As a result AgentCat now injects a session_id on every MCP tool call to associate them under the same task umbrella. Our evals show much higher tool correlation accuracy at the cost of < 1% additional context pollution.

[!IMPORTANT] MCPcat is now AgentCat 🐱 — same team, same product, new name. This module was previously published as mcpcat-go-sdk, which keeps working forever, but new features land here. Upgrading takes a few minutes — see the migration guide.

AgentCat is an analytics platform for MCP server owners 🐱. It captures user intentions and behavior patterns to help you understand what AI users actually need from your tools — eliminating guesswork and accelerating product development all with one-line of code.

This SDK also provides a free and simple way to forward telemetry like logs, traces, and errors to any Open Telemetry collector or popular tools like Datadog, Sentry, and PostHog.

# mark3labs/mcp-go (v0.53.0 – v0.57.0)
go get go.agentcat.com/sdk/mcpgo/v2

# official modelcontextprotocol/go-sdk (v1.4.1 – v1.7.0)
go get go.agentcat.com/sdk/officialsdk/v2

To learn more about us, check us out here. For detailed guides visit our documentation.

Why use AgentCat? 🤔

AgentCat helps builders of MCP servers, Claude Connectors, and ChatGPT Plugins learn how to improve them by capturing any agents goals and detecting when they get stuck.

Use AgentCat for:

• Agent session replay 🎬. Follow alongside your users and their agents to understand why they're using your MCP servers, what functionality you're missing, and what clients they're coming from.
• Trace debugging 🔍. See where your users are getting stuck, track and find when LLMs get confused by your API, and debug sessions across all deployments of your MCP server.
• Existing platform support 📊. Get logging and tracing out of the box for your existing observability platforms (OpenTelemetry, Datadog, Sentry) — eliminating the tedious work of implementing telemetry yourself.

How it works

AgentCat works as a lightweight middleware inside your MCP server. When you call Track(), it seamlessly modifies your registered tool schemas in place, following the MCP core team's explicit handles (SEP-2567) guidelines. Concretely, AgentCat adds the following to your server:

• session_id — a parameter injected into each tool's input schema. Agents echo it back on every call, letting AgentCat group related tool calls into one task even over stateless transports. Values are validated: anything AgentCat did not issue is rejected rather than adopted, and the agent is told to re-send the ID it was given.
• agent_id (off by default) — enabled with EnableAgentTracking: true. Each agent self-generates its own ID, keeping parallel agents working the same task individually attributable.
• context — a parameter asking the agent to explain, in one sentence, why it is making this call. This is where intent data comes from.
• get_more_tools — an additional tool, prompt-engineered so that agents readily report the features and tools they looked for but couldn't find — surfacing your missing functionality directly from real usage.

Injected parameters are stripped from arguments before your tool handler runs, so your code never sees them. For tools that declare an output schema, issued IDs are also mirrored into structuredContent (as _mcp_instructions), so clients that only read structured results still receive them.

Getting Started

To get started with AgentCat, first create an account and obtain your project ID by signing up at agentcat.com. For detailed setup instructions visit our documentation.

Once you have your project ID, integrate AgentCat into your MCP server:

mark3labs/mcp-go:

import agentcat "go.agentcat.com/sdk/mcpgo/v2"

// Track the server with AgentCat
shutdown, err := agentcat.Track(mcpServer, "proj_0000000", nil)
if err != nil { log.Fatal(err) } // on error shutdown is nil — do not defer it
defer shutdown(context.Background()) // flushes queued events before exit

Official go-sdk:

import agentcat "go.agentcat.com/sdk/officialsdk/v2"

// Track the server with AgentCat
shutdown, err := agentcat.Track(mcpServer, "proj_0000000", nil)
if err != nil { log.Fatal(err) } // on error shutdown is nil — do not defer it
defer shutdown(context.Background()) // flushes queued events before exit

Stateless servers built on MCP 2026-07-28 create a fresh server instance per request (mcp.NewStreamableHTTPHandler) or per connection. Call Track() inside the factory so every instance is tracked:

// A complete runnable program is in examples/officialsdk/factory.
handler := mcp.NewStreamableHTTPHandler(func(r *http.Request) *mcp.Server {
    s := newServer()
    if _, err := agentcat.Track(s, "proj_0000000", nil); err != nil {
        log.Printf("agentcat: %v", err) // never fail a request over analytics
    }
    return s // skip the per-server shutdown here; drain once at exit with agentcat.Shutdown(ctx)
}, &mcp.StreamableHTTPOptions{Stateless: true})

Calling Track() per instance is cheap — the event queue, telemetry exporters, and diagnostics are initialized once and shared across instances.

Identifying users

We strongly encourage identifying every actor. If you can't resolve a real user, return a stable anonymized ID instead — for example, a hash of the auth token or API key — so that all events from the same end user still roll up to one actor in your dashboard rather than scattering into anonymous one-off sessions.

Identify runs on every tool call, uncached, and stamps only that one event. Because it is on the hot path of every call, keep it cheap: read from the context, headers, or an already-parsed token, and make no network calls. Return nil (or an identity with an empty UserID) to skip identification for a call.

The callback receives the raw MCP request — in both adapters the value passed is the *mcp.CallToolRequest that triggered the event:

mark3labs/mcp-go:

import (
    "github.com/mark3labs/mcp-go/mcp"
    agentcat "go.agentcat.com/sdk/mcpgo/v2"
)

shutdown, err := agentcat.Track(mcpServer, "proj_0000000", &agentcat.Options{
    Identify: func(ctx context.Context, request any) *agentcat.UserIdentity {
        req := request.(*mcp.CallToolRequest) // always a tool call in v2
        _ = req // extract identity from the request, ctx, headers, or an auth token
        return &agentcat.UserIdentity{
            UserID: "user_12345", UserName: "demo_user",
            UserData: map[string]any{"email": "demo@example.com"},
        }
    },
})

Official go-sdk:

import (
    "github.com/modelcontextprotocol/go-sdk/mcp"
    agentcat "go.agentcat.com/sdk/officialsdk/v2"
)

shutdown, err := agentcat.Track(mcpServer, "proj_0000000", &agentcat.Options{
    Identify: func(ctx context.Context, request mcp.Request) *agentcat.UserIdentity {
        req := request.(*mcp.CallToolRequest) // always a tool call in v2
        _ = req // extract identity from the request, ctx, headers, or an auth token
        return &agentcat.UserIdentity{
            UserID: "user_12345", UserName: "demo_user",
            UserData: map[string]any{"email": "demo@example.com"},
        }
    },
})

Redacting sensitive data

AgentCat redacts all data sent to its servers and encrypts at rest, but for additional security, it offers a hook to do your own redaction on all text data returned back to our servers.

shutdown, err := agentcat.Track(mcpServer, "proj_0000000", &agentcat.Options{
    RedactSensitiveInformation: func(text string) string {
        return redact(text)
    },
})

For redaction decisions that need more context than a single string — such as which tool was called or what type of event is being published — use the event-level RedactEvent hook. It receives the full event object and returns a modified event, or nil to drop the event entirely. It can be combined with RedactSensitiveInformation.

shutdown, err := agentcat.Track(mcpServer, "proj_0000000", &agentcat.Options{
    RedactEvent: func(event *agentcat.Event) (*agentcat.Event, error) {
        // Drop events from tools that handle secrets entirely
        if event.GetResourceName() == "get_credentials" {
            return nil, nil
        }
        // Strip response payloads from a specific tool
        if event.GetResourceName() == "export_report" {
            event.Response = nil
        }
        return event, nil
    },
})

Vendor Support

AgentCat seamlessly integrates with your existing observability stack, providing automatic logging and tracing without the tedious setup typically required. Export telemetry data to multiple platforms simultaneously:

shutdown, err := agentcat.Track(mcpServer, "proj_0000", &agentcat.Options{
    // Project ID can optionally be "" if you just want to forward telemetry
    Exporters: map[string]agentcat.ExporterConfig{
        "otlp": {
            Type:     "otlp",
            Endpoint: "http://localhost:4318", // /v1/traces is appended automatically
        },
        "datadog": {
            Type:    "datadog",
            APIKey:  os.Getenv("DD_API_KEY"),
            Site:    "datadoghq.com",
            Service: "my-mcp-server",
        },
        "sentry": {
            Type:        "sentry",
            DSN:         os.Getenv("SENTRY_DSN"),
            Environment: "production",
        },
        "posthog": {
            Type:   "posthog",
            APIKey: os.Getenv("POSTHOG_API_KEY"),
            Host:   "https://us.i.posthog.com", // Optional: defaults to US region
        },
    },
})

Learn more about our free and open source telemetry integrations.

Internal diagnostics

To help us catch and fix broken installs, the SDK sends AgentCat a small, anonymized signal when setup or runtime errors occur — never your tool calls, your responses, or anything about your users. Records carry only operational metadata, such as your project ID (or an anonymous install ID when none is set). Your local ~/agentcat.log is unchanged.

Diagnostics are on by default and can be turned off completely with either:

• agentcat.Options{DisableDiagnostics: true} passed to Track, or
• the DISABLE_DIAGNOSTICS environment variable.

Free for open source

AgentCat is free for qualified open source projects. We believe in supporting the ecosystem that makes MCP possible. If you maintain an open source MCP server, you can access our full analytics platform at no cost.

How to apply: Email hi@agentcat.com with your repository link

Already using AgentCat? We'll upgrade your account immediately.

Community Cats 🐱

Meet the cats behind AgentCat! Add your cat to our community by submitting a PR with your cat's photo in the docs/cats/ directory.

Want to add your cat? Create a PR adding your cat's photo to docs/cats/ and update this section!

Documentation

Overview

Package agentcat is the shared integration surface of the AgentCat Go SDK.

Which package do I import?

If you are instrumenting an MCP server, you want an ADAPTER, not this package:

go.agentcat.com/sdk/mcpgo/v2        // github.com/mark3labs/mcp-go servers
go.agentcat.com/sdk/officialsdk/v2  // github.com/modelcontextprotocol/go-sdk servers

Each adapter exposes a single Track entry point plus its own Options, and re-exports every type an end user needs (UserIdentity, Event, ExporterConfig, CustomEventData), so a customer's server never imports this package directly.

What is in here

This package holds everything the two adapters share and neither may duplicate: the pure schema-injection engine, the stateless session/agent handle primitives, the agent-facing copy (byte-identical across every AgentCat SDK), event construction, the server registry, and the publisher. The adapters live in their own Go modules, so they cannot reach this module's internal/ packages — everything they need is re-exported here, and nothing else is exported.

The API here is stable for the adapters that ship with this SDK. It is not a general-purpose API: it may change in a minor release if both adapters change with it.

How the pieces fit together

On tools/list an adapter normalises its library's tools into []NormalizedTool, calls BuildInjectedTools, writes the mutated schemas back onto its own copies, and folds the returned Registries into the server's AgentCatInstance. On tools/call it resolves handles with ResolveSessionHandle, removes what the registries say it injected with StripToolArguments, dispatches, decorates a COPY of the response with BuildMintBackText and BuildHandleMirror (the wire only — the published event always carries the customer's raw request and undecorated response), and publishes one event built by NewToolCallEvent.

Index

• Constants
• Variables
• func ApplySDKTags(evt *Event, ec *EventContext)
• func AttachEventMetadata(evt *Event, tags func() map[string]string, properties func() map[string]any)
• func BuildHandleMirror(in MirrorInput) map[string]any
• func BuildInjectedTools(cfg InjectConfig, tools []NormalizedTool) ([]NormalizedTool, *Registries)
• func BuildMintBackText(res SessionResolution) string
• func ClampAgentID(v string) string
• func ConvertToMap(v any) any
• func DeriveSessionID(customerID, projectID string) string
• func ExtractHandle(args map[string]any, name string) (string, bool)
• func GetDependencyVersion(modulePath string) string
• func InitDiagnostics(projectID string, disabled bool, integration, mcpSDKPath string)
• func InitPublisher(redactFn RedactFunc, redactEventFn RedactEventFunc, apiBaseURL string, ...) func(evt *Event)
• func IsValidSessionID(value string) bool
• func LogRecoveredPanic(where string, recovered any)
• func LogSetupComplete(projectID string, opts *Options)
• func LogSetupFailed(reason string)
• func LogWarn(format string, args ...any)
• func MintSessionID() string
• func NewEventID() string
• func Ptr[T any](v T) *T
• func PublishCustomEvent(serverOrSessionID any, projectID string, data *CustomEventData) error
• func RedactEvent(evt *Event, redactFn RedactFunc) error
• func RegisterServer[T any](server *T, instance *AgentCatInstance)
• func ReportSessionParamCollisions(instance *AgentCatInstance, reg *Registries)
• func ResetDiagnosticsForTest()
• func ResolveAPIBaseURL(optionURL string) string
• func ResolveContextDescription(custom string) string
• func SessionParamIsOurs(toolName string, reg *Registries) bool
• func SetDebug(debug bool)
• func ShouldMirror(toolName string, reg *Registries) bool
• func Shutdown(ctx context.Context) error
• func StripToolArguments(toolName string, args map[string]any, reg *Registries) map[string]any
• func UnregisterServer(server any)
• func ValidateTags(tags map[string]string) map[string]string
• type AgentCatInstance
  • func GetInstance(server any) *AgentCatInstance
• type CustomEventData
• type Event
  • func NewToolCallEvent(ec *EventContext, duration *int32, isError bool, errorDetails error) *Event
• type EventContext
• type Exporter
• type ExporterConfig
• type IDPrefix
• type InjectConfig
  • func BuildInjectConfig(opts *Options, hookMode bool) InjectConfig
• type MCPcatInstance
• type MirrorInput
• type NormalizedTool
• type Options
  • func DefaultOptions() Options
• type RedactEventFunc
• type RedactFunc
• type Registries
• type SchemaObject
  • func NewSchemaObject() *SchemaObject
  • func ParseSchemaObject(raw []byte) (*SchemaObject, error)
• type SessionResolution
  • func ResolveSessionHandle(args map[string]any, hook func() (string, error), projectID string, ...) SessionResolution
• type SessionSource
• type UserIdentity

Constants

const (
	// SessionSourceSupplied: the agent echoed a session_id argument.
	SessionSourceSupplied = handles.SessionSourceSupplied
	// SessionSourceMinted: this SDK issued a fresh session for this call.
	SessionSourceMinted = handles.SessionSourceMinted
	// SessionSourceHook: derived from the customer's ResolveSessionID callback.
	SessionSourceHook = handles.SessionSourceHook
	// SessionSourceInvalid: the agent sent a session_id this server never
	// issued. The call publishes sessionless and the agent is told to re-send
	// the real one.
	SessionSourceInvalid = handles.SessionSourceInvalid
	// SessionSourceForeign: the customer's own tool declares session_id, so
	// AgentCat never injected one there. The call publishes sessionless and
	// nothing is said to the agent about a parameter that is not ours.
	SessionSourceForeign = handles.SessionSourceForeign
)

const (
	// ParamSessionID, ParamAgentID and ParamContext are the three parameter
	// names this SDK may inject into a tool's input schema.
	ParamSessionID = constants.ParamSessionID
	ParamAgentID   = constants.ParamAgentID
	ParamContext   = constants.ParamContext

	// MCPInstructionsKey is the structuredContent member carrying the handle
	// mirror, and the property declared on extended output schemas.
	MCPInstructionsKey = constants.MCPInstructionsKey

	// MetaClientInfoKey and MetaProtocolVersionKey are the reserved _meta keys
	// a 2026-07-28 client stamps on every request.
	MetaClientInfoKey      = constants.MetaClientInfoKey
	MetaProtocolVersionKey = constants.MetaProtocolVersionKey

	// The SDK-owned event tags. These are set on every published event and
	// are exempt from the customer tag cap.
	TagSessionSource   = constants.TagSessionSource
	TagAgentID         = constants.TagAgentID
	TagAgentSource     = constants.TagAgentSource
	TagProtocolVersion = constants.TagProtocolVersion
	TagMRTR            = constants.TagMRTR

	// MRTR tag values: an intermediate round that asked the client for input,
	// and the continuation round that answered one.
	MRTRInputRequired = constants.MRTRInputRequired
	MRTRContinuation  = constants.MRTRContinuation

	// The optional get_more_tools tool's name and agent-facing copy.
	GetMoreToolsName               = constants.GetMoreToolsName
	GetMoreToolsDescription        = constants.GetMoreToolsDescription
	GetMoreToolsContextDescription = constants.GetMoreToolsContextDescription
	GetMoreToolsResponseText       = constants.GetMoreToolsResponseText
)

Wire keys, injected parameter names, tags, and agent-facing copy shared with the adapters (which cannot import internal/ across module boundaries).

Every agent-facing string here is byte-identical to the TypeScript SDK and is defined exactly once, in internal/constants. Never retype one of these values as a literal — not in an adapter, not in a test.

const CustomEventType = "agentcat:custom"

CustomEventType is the wire event type for customer-published custom events.

const DefaultContextDescription = `` /* 532-byte string literal not displayed */

DefaultContextDescription is the default description for the "context" parameter that both adapters inject into tool input schemas, used when no CustomContextDescription is configured.

const SDKModulePath = core.SDKModulePath

SDKModulePath is this SDK's root module path, used to resolve its own version.

Variables

var (
	ErrServerNotTracked = errors.New("agentcat: server is not tracked; call Track first or provide a session ID string")
	ErrInvalidTarget    = errors.New("agentcat: first parameter must be either an MCP server or a session ID string")
)

Sentinel errors for PublishCustomEvent validation.

var (
	ErrNilServer      = errors.New("agentcat: server must not be nil")
	ErrEmptyProjectID = errors.New("agentcat: projectID must not be empty")
)

Sentinel errors for Track validation.

Functions

func ApplySDKTags

func ApplySDKTags(evt *Event, ec *EventContext)

ApplySDKTags stamps the SDK-owned tags (session source, agent ID and its source, protocol version, MRTR) onto an event. Call it AFTER the customer's own tags: the SDK's win, and they are exempt from the customer tag cap.

func AttachEventMetadata

func AttachEventMetadata(evt *Event, tags func() map[string]string, properties func() map[string]any)

AttachEventMetadata resolves customer-defined tags and properties via the given callbacks and attaches them to the event's wire fields. Integration API for adapter modules: each adapter constructs the closures from its typed Options callbacks. Either callback may be nil (skipped). A panic in a callback is swallowed so the event is still published without that metadata; tags are validated via ValidateTags and empty property maps are dropped.

func BuildHandleMirror

func BuildHandleMirror(in MirrorInput) map[string]any

BuildHandleMirror assembles the _mcp_instructions value mirrored into a response's structuredContent. Returns nil when there is nothing the agent could echo back.

func BuildInjectedTools

func BuildInjectedTools(cfg InjectConfig, tools []NormalizedTool) ([]NormalizedTool, *Registries)

BuildInjectedTools runs the pure injection pipeline: it returns the advertised tools and the registries describing exactly what it injected. Pure, deterministic, and idempotent — it never mutates its inputs and never fails a tool list; a tool it cannot safely touch passes through with an empty registry entry.

func BuildMintBackText

func BuildMintBackText(res SessionResolution) string

BuildMintBackText renders the trailing [MCP INSTRUCTIONS] content block for one call, or "" when there is nothing to say. It is the single decision point for whether a call announces anything: minted announces the new handle, invalid corrects the agent without issuing a replacement, and hook, foreign and supplied say nothing. Adapters must not re-derive it.

func ClampAgentID

func ClampAgentID(v string) string

ClampAgentID prepares a supplied agent_id for the SDK tag channel, which bypasses customer tag validation: newlines become spaces and the value is truncated to 200 bytes on a rune boundary.

func ConvertToMap

func ConvertToMap(v any) any

ConvertToMap converts any value to map[string]any or []any via JSON round-trip.

func DeriveSessionID

func DeriveSessionID(customerID, projectID string) string

DeriveSessionID maps a customer correlation ID (plus the project ID) onto a stable ses_ session ID. Deterministic across processes, restarts, and every AgentCat SDK: the same input always yields the same session.

func ExtractHandle

func ExtractHandle(args map[string]any, name string) (string, bool)

ExtractHandle returns args[name] when it is a string with non-blank content, VERBATIM (never trimmed or reformatted). It is shape-agnostic because it is shared with agent_id, which this SDK never validates; ResolveSessionHandle applies IsValidSessionID to the session handle.

func GetDependencyVersion

func GetDependencyVersion(modulePath string) string

GetDependencyVersion returns the version of the given module from build info, or "dev" if the module is not found.

func InitDiagnostics

func InitDiagnostics(projectID string, disabled bool, integration, mcpSDKPath string)

InitDiagnostics initializes internal SDK diagnostics and emits the setup-start beacon. Call it early in Track — before validation — so setup failures are captured. Idempotent across the process.

func InitPublisher

func InitPublisher(redactFn RedactFunc, redactEventFn RedactEventFunc, apiBaseURL string, exporterConfigs map[string]ExporterConfig) func(evt *Event)

InitPublisher initializes the global event publisher and returns a publish function. The returned function can be called to publish events asynchronously. If apiBaseURL is empty, the default AgentCat API URL is used. When exporter configs are provided, every published event is also fanned out to the configured telemetry exporters, independently of the AgentCat API send.

func IsValidSessionID

func IsValidSessionID(value string) bool

IsValidSessionID reports whether value is a session ID this SDK issued — the ses_ prefix plus a 27-character base62 KSUID. Anything else was invented by the agent or belongs to someone else, and is never adopted into Event.SessionId, which both redaction hooks are exempt from.

func LogRecoveredPanic

func LogRecoveredPanic(where string, recovered any)

LogRecoveredPanic logs a panic recovered inside SDK capture code (hooks, middleware, capture goroutines). Integration API for adapter modules: analytics failures must never crash the customer's server, so capture code recovers, calls this, and drops the event.

func LogSetupComplete

func LogSetupComplete(projectID string, opts *Options)

LogSetupComplete emits the setup-complete beacon (metadata only).

func LogSetupFailed

func LogSetupFailed(reason string)

LogSetupFailed logs a setup failure as ERROR so it surfaces in diagnostics.

func LogWarn

func LogWarn(format string, args ...any)

LogWarn writes a warning to ~/agentcat.log. Integration API for the adapter modules, which cannot reach internal/logging across the module boundary. Use it for degraded-but-safe outcomes the customer may want to know about (a schema AgentCat could not read, a dropped event); anything that breaks capture outright belongs in LogRecoveredPanic or LogSetupFailed.

func MintSessionID

func MintSessionID() string

MintSessionID returns a fresh random ses_-prefixed session ID.

func NewEventID

func NewEventID() string

NewEventID generates a new unique event ID with the AgentCat prefix.

func Ptr

func Ptr[T any](v T) *T

Ptr returns a pointer to the given value. Convenience helper for integration modules.

func PublishCustomEvent

func PublishCustomEvent(serverOrSessionID any, projectID string, data *CustomEventData) error

PublishCustomEvent publishes a customer-defined event to AgentCat.

serverOrSessionID is either a tracked MCP server instance (any server previously passed to an adapter's Track function) or a session ID string. A string is used verbatim as the event's session ID — no derivation or validation is applied — so events correlate with whatever session or correlation ID the caller already holds. For a tracked server, the event publishes without a session unless one is provided via data.SessionID. A non-empty data.SessionID always takes precedence over a string target.

projectID is required. data is optional event payload.

func RedactEvent

func RedactEvent(evt *Event, redactFn RedactFunc) error

RedactEvent applies the redaction function to sensitive fields in the event.

func RegisterServer

func RegisterServer[T any](server *T, instance *AgentCatInstance)

RegisterServer stores the AgentCat instance for a given server in the global registry.

func ReportSessionParamCollisions

func ReportSessionParamCollisions(instance *AgentCatInstance, reg *Registries)

ReportSessionParamCollisions logs, at most once per tool per tracked server, each customer-declared session_id parameter the engine refused to overwrite. Adapters call it after storing the registries a tools/list produced.

A session_id collision is an ERROR rather than a warning because it costs the customer correlation outright: every call to that tool publishes without a session and cannot be grouped with anything else. agent_id and context collisions stay warnings — they lose an attribute, not the thread.

Logging only. It reads the registries the pure engine produced and never affects them, so inject.Build stays deterministic.

func ResetDiagnosticsForTest

func ResetDiagnosticsForTest()

ResetDiagnosticsForTest resets internal diagnostics + logging sink state. For tests.

func ResolveAPIBaseURL

func ResolveAPIBaseURL(optionURL string) string

ResolveAPIBaseURL returns the API base URL to use, applying the priority: code option > AGENTCAT_API_URL env var > MCPCAT_API_URL env var (legacy fallback) > empty string (publisher uses default).

func ResolveContextDescription

func ResolveContextDescription(custom string) string

ResolveContextDescription returns the custom context-parameter description when non-empty, or DefaultContextDescription otherwise.

func SessionParamIsOurs

func SessionParamIsOurs(toolName string, reg *Registries) bool

SessionParamIsOurs reports whether the session_id argument on a call to toolName is AgentCat's to read. A tool absent from the registries counts as ours, so a call arriving before any tools/list is still validated.

func SetDebug

func SetDebug(debug bool)

SetDebug enables or disables debug logging globally.

func ShouldMirror

func ShouldMirror(toolName string, reg *Registries) bool

ShouldMirror reports whether this tool's declared output schema was extended to allow the mirror. Writing the mirror into a response whose schema does not declare it would fail the customer's own output validation.

func Shutdown

func Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the global event publisher. This should be called when the application is shutting down to ensure all queued events are published before exit. The provided context controls the shutdown deadline; if no deadline is set, a default 5-second timeout is applied.

func StripToolArguments

func StripToolArguments(toolName string, args map[string]any, reg *Registries) map[string]any

StripToolArguments returns a COPY of args with only the parameters the registries say this SDK injected for this tool removed. The customer's request object is never mutated, and the raw arguments still go on the published event. With no registries at all it falls back to removing the three injectable names heuristically.

func UnregisterServer

func UnregisterServer(server any)

UnregisterServer removes a server from the global registry.

func ValidateTags

func ValidateTags(tags map[string]string) map[string]string

ValidateTags validates customer-supplied event tags against AgentCat's client-side constraints, dropping (and warn-logging) invalid entries. Returns nil when no valid entries remain.

Types

type AgentCatInstance

type AgentCatInstance = core.AgentCatInstance

AgentCatInstance is the per-server tracked state the registry holds: project, options, injection registries, and the rebuild hook.

func GetInstance

func GetInstance(server any) *AgentCatInstance

GetInstance retrieves the AgentCat instance for a given server from the global registry.

type CustomEventData

type CustomEventData = core.CustomEventData

CustomEventData describes a customer-defined event.

type Event

type Event = core.Event

Event is a published event, as the RedactEvent hook sees it.

func NewToolCallEvent

func NewToolCallEvent(ec *EventContext, duration *int32, isError bool, errorDetails error) *Event

NewToolCallEvent builds the single mcp:tools/call event for one call. duration is nil when nothing of this SDK's timed the call. Returns nil when the context is unusable.

type EventContext

type EventContext = event.EventContext

EventContext is the per-request identity and handle state an adapter resolves before building an event.

type Exporter

type Exporter = core.Exporter

Exporter forwards published events to an external telemetry system.

type ExporterConfig

type ExporterConfig = core.ExporterConfig

ExporterConfig configures one telemetry exporter.

type IDPrefix

type IDPrefix = core.IDPrefix

IDPrefix is the leading segment of an AgentCat-generated ID.

const (
	PrefixSession IDPrefix = core.PrefixSession
	PrefixEvent   IDPrefix = core.PrefixEvent

	// PrefixAgent is reserved across every AgentCat SDK. Nothing mints it —
	// agent IDs are self-chosen by the agent — but the prefix must never be
	// reused for anything else.
	PrefixAgent IDPrefix = core.PrefixAgent
)

type InjectConfig

type InjectConfig = inject.Config

InjectConfig selects what the engine injects. Build it with BuildInjectConfig; never assemble one by hand.

func BuildInjectConfig

func BuildInjectConfig(opts *Options, hookMode bool) InjectConfig

BuildInjectConfig derives the pure pipeline config from tracked options. Deterministic: rebuild-on-demand depends on Build(cfg, tools) producing identical registries on every server instance. Adapters pass hookMode = (their Options.ResolveSessionID != nil).

type MCPcatInstance

type MCPcatInstance = AgentCatInstance

MCPcatInstance is the former name of AgentCatInstance.

Deprecated: use AgentCatInstance.

type MirrorInput

type MirrorInput = inject.MirrorInput

MirrorInput describes what the structured mirror may name for one call.

type NormalizedTool

type NormalizedTool = inject.NormalizedTool

NormalizedTool is the engine's library-neutral view of one tool. An adapter builds these from its library's tools and writes the mutated schemas back onto its own copies afterwards.

type Options

type Options = core.Options

Options is the library-neutral tracked configuration. Each adapter maps its own public Options onto this once, at Track time.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the library-neutral options with every feature at its default (all Disable* flags false).

type RedactEventFunc

type RedactEventFunc = core.RedactEventFunc

RedactEventFunc is the event-level redaction hook; returning nil drops the event.

type RedactFunc

type RedactFunc = core.RedactFunc

RedactFunc redacts sensitive text before an event is published.

type Registries

type Registries = inject.Registries

Registries record exactly what the engine injected per tool. They drive argument stripping (StripToolArguments) and the mirror gate (ShouldMirror), so an adapter must keep them alive for every tool that has ever been listed — see AgentCatInstance.MergeRegistries.

type SchemaObject

type SchemaObject = inject.SchemaObject

SchemaObject is a JSON object that preserves key order and the raw bytes of every value, so a customer's schema round-trips byte for byte through injection.

func NewSchemaObject

func NewSchemaObject() *SchemaObject

NewSchemaObject returns an empty ordered JSON object.

func ParseSchemaObject

func ParseSchemaObject(raw []byte) (*SchemaObject, error)

ParseSchemaObject parses raw as a JSON object, preserving key order. An error means the document is not a JSON object; the adapter must then treat the schema as opaque and advertise it untouched rather than replace it.

type SessionResolution

type SessionResolution = handles.SessionResolution

SessionResolution is the outcome of one call's stateless session resolution.

func ResolveSessionHandle

func ResolveSessionHandle(args map[string]any, hook func() (string, error), projectID string, sessionParamIsOurs bool) SessionResolution

ResolveSessionHandle resolves the session for one call, statelessly. hook is non-nil in hook mode (the adapter closes over the customer's ResolveSessionID), in which case the supplied arguments are ignored entirely. Never fails: a blank, errored, or panicking hook mints a session silently.

sessionParamIsOurs comes from SessionParamIsOurs and must be computed from registries the adapter has already loaded — resolve AFTER loading them. Passing true for a tool the customer owns would adopt their value.

type SessionSource

type SessionSource = handles.SessionSource

SessionSource records how a call's session ID was obtained: echoed by the agent, minted by this SDK, or derived from the customer's hook.

type UserIdentity

type UserIdentity = core.UserIdentity

UserIdentity names the actor behind a call, as an adapter's Identify callback returned it.