agentcat

README

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

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

[!NOTE] Looking for the Python SDK? Check it out here agentcat-python.

Why use AgentCat? 🤔

AgentCat helps developers and product owners build, improve, and monitor their MCP servers by capturing user analytics and tracing tool calls.

Use AgentCat for:

• User session replay 🎬. Follow alongside your users 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.

Supported MCP Libraries

AgentCat provides first-class support for the two most popular Go MCP libraries:

Library	Install
mcp-go (mark3labs)	go get go.agentcat.com/sdk/mcpgo
go-sdk (official)	go get go.agentcat.com/sdk/officialsdk

Import the package that matches the MCP library you're already using. Both expose the same Track() API and share the same feature set.

Getting Started

Create an account and obtain your project ID at agentcat.com. For detailed setup instructions visit our documentation.

Add one Track() call before starting your server:

mark3labs/mcp-go:

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

shutdown, err := agentcat.Track(mcpServer, "proj_YOUR_PROJECT_ID", nil)
if err != nil { /* handle error */ }
defer shutdown(context.Background())

Official go-sdk:

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

shutdown, err := agentcat.Track(mcpServer, "proj_YOUR_PROJECT_ID", nil)
if err != nil { /* handle error */ }
defer shutdown(context.Background())

Track() returns a shutdown function — call it before your application exits to flush all queued events.

Advanced Features

User Identification

Identify your user sessions with a callback to attach user information to every event in a session.

mark3labs/mcp-go:

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

shutdown, err := agentcat.Track(s, "proj_YOUR_PROJECT_ID", &agentcat.Options{
    Identify: func(ctx context.Context, req *mcp.CallToolRequest) *agentcat.UserIdentity {
        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"
)

shutdown, err := agentcat.Track(s, "proj_YOUR_PROJECT_ID", &agentcat.Options{
    Identify: func(ctx context.Context, req *mcp.CallToolRequest) *agentcat.UserIdentity {
        return &agentcat.UserIdentity{
            UserID: "user_12345", UserName: "demo_user",
            UserData: map[string]any{"email": "demo@example.com"},
        }
    },
})

Sensitive Data Redaction

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 before it leaves your server.

shutdown, err := agentcat.Track(s, "proj_YOUR_PROJECT_ID", &agentcat.Options{
    RedactSensitiveInformation: func(text string) string {
        return emailRegex.ReplaceAllString(text, "[REDACTED]")
    },
})

Debug Mode

Enable debug logging for troubleshooting. Debug logs are written to ~/mcpcat.log.

shutdown, err := agentcat.Track(s, "proj_YOUR_PROJECT_ID", &agentcat.Options{Debug: true})

Using with Existing Hooks (mcp-go only)

If your server already uses mcp-go hooks, pass them via Options.Hooks and AgentCat will append its hooks alongside yours:

shutdown, err := agentcat.Track(s, "proj_YOUR_PROJECT_ID", &agentcat.Options{Hooks: hooks})

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), SDK version, and Go runtime/OS/arch. Your local ~/mcpcat.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.

Configuration Options

Option	Type	Default	Description
DisableReportMissing	bool	false	When true, prevents the get_more_tools tool from being registered
DisableToolCallContext	bool	false	When true, prevents the context parameter from being injected on tool calls
Debug	bool	false	Enable debug logging to ~/mcpcat.log
RedactSensitiveInformation	func(string) string	nil	Custom redaction applied to all text data before sending
Identify	callback	nil	Attach user information to sessions
Hooks	*server.Hooks	nil	Pre-existing hooks to merge with (mcp-go only)

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

Index

• Variables
• func ConvertToMap(v any) any
• func GetDependencyVersion(modulePath string) string
• func InitDiagnostics(projectID string, disabled bool, integration, mcpSDKPath string)
• func InitPublisher(redactFn RedactFunc, apiBaseURL string) func(evt *Event)
• func LogSetupComplete(projectID string, opts *Options)
• func LogSetupFailed(reason string)
• func NewEventID() string
• func NewSessionID() string
• func Ptr[T any](v T) *T
• func RedactEvent(evt *Event, redactFn RedactFunc) error
• func RegisterServer(server any, instance *MCPcatInstance)
• func ResetDiagnosticsForTest()
• func ResolveAPIBaseURL(optionURL string) string
• func SetDebug(debug bool)
• func Shutdown(ctx context.Context) error
• func UnregisterServer(server any)
• type Event
  • func CreateIdentifyEvent(sess *Session) *Event
  • func NewEvent(sess *Session, eventType string, duration *int32, isError bool, ...) *Event
• type Exporter
• type ExporterConfig
• type IDPrefix
• type MCPcatInstance
  • func GetInstance(server any) *MCPcatInstance
• type Options
  • func DefaultOptions() Options
• type ProtectedSession
• type RedactFunc
• type Session
• type SessionMap
  • func NewSessionMap(ttl time.Duration) *SessionMap
• type UserIdentity

Variables

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

Sentinel errors for Track validation.

Functions

func ConvertToMap

func ConvertToMap(v any) any

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

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, apiBaseURL string) 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 MCPCat API URL is used.

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 NewEventID

func NewEventID() string

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

func NewSessionID

func NewSessionID() string

NewSessionID generates a new unique session ID with the MCPCat prefix.

func Ptr

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

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

func RedactEvent

func RedactEvent(evt *Event, redactFn RedactFunc) error

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

func RegisterServer

func RegisterServer(server any, instance *MCPcatInstance)

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

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 > MCPCAT_API_URL env var > empty string (publisher uses default).

func SetDebug

func SetDebug(debug bool)

SetDebug enables or disables debug logging globally.

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 UnregisterServer

func UnregisterServer(server any)

UnregisterServer removes a server from the global registry.

Types

type Event

type Event = core.Event

func CreateIdentifyEvent

func CreateIdentifyEvent(sess *Session) *Event

CreateIdentifyEvent creates an Event for mcpcat:identify event type.

func NewEvent

func NewEvent(sess *Session, eventType string, duration *int32, isError bool, errorDetails error) *Event

NewEvent creates an SDK-agnostic event from session data and basic metadata.

type Exporter

type Exporter = core.Exporter

type ExporterConfig

type ExporterConfig = core.ExporterConfig

type IDPrefix

type IDPrefix = core.IDPrefix

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

type MCPcatInstance

type MCPcatInstance = core.MCPcatInstance

func GetInstance

func GetInstance(server any) *MCPcatInstance

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

type Options

type Options = core.Options

func DefaultOptions

func DefaultOptions() Options

type ProtectedSession

type ProtectedSession = sessionmap.ProtectedSession

type RedactFunc

type RedactFunc = core.RedactFunc

type Session

type Session = core.Session

type SessionMap

type SessionMap = sessionmap.SessionMap

func NewSessionMap

func NewSessionMap(ttl time.Duration) *SessionMap

NewSessionMap creates a session map with TTL-based eviction. If ttl is 0, a 30-minute default is used.

type UserIdentity

type UserIdentity = core.UserIdentity