agnost-go

README

Agnost Analytics SDK for Go

Track and analyze your MCP (Model Context Protocol) servers built with mcp-go using Agnost Analytics.

Features

• 🚀 Simple API: Just Track(server, orgID, config)
• 📊 Comprehensive Analytics: Track tool usage, latency, and success rates
• 🔒 Privacy Controls: Disable input/output tracking as needed
• ⚡ High Performance: Goroutine-based event queuing with minimal overhead
• 🎯 Type-Safe: Full Go type safety with compile-time checks
• 👤 User Identification: Optional user tracking with custom identify functions

Installation

go get github.com/agnostai/agnost-go

Quick Start

package main

import (
    "github.com/agnostai/agnost-go/agnost"
    "github.com/mark3labs/mcp-go/server"
)

func main() {
    // Create your MCP server
    s := server.NewMCPServer("my-server", "1.0.0")

    // Add your tools here...

    // Track with Agnost
    agnost.Track(s, "your-org-id", &agnost.Config{
        DisableInput:  false,
        DisableOutput: false,
        BatchSize:     10,
        LogLevel:      "info",
    })

    // Start server
    server.ServeStdio(s)
}

Usage

Basic Tracking

agnost.Track(server, "your-org-id", &agnost.Config{
    BatchSize: 10,
    LogLevel:  "info",
})

With User Identification

agnost.Track(server, "your-org-id", &agnost.Config{
    Identify: func(req *http.Request, env map[string]string) *agnost.UserIdentity {
        return &agnost.UserIdentity{
            UserID: env["USER_ID"],
            Email:  env["USER_EMAIL"],
            Role:   env["USER_ROLE"],
        }
    },
})

Privacy Controls

agnost.Track(server, "your-org-id", &agnost.Config{
    DisableInput:  true,  // Don't track input arguments
    DisableOutput: true,  // Don't track output results
})

Configuration

Config Options

type Config struct {
    // Endpoint is the Agnost Analytics API endpoint
    Endpoint string  // default: "https://api.agnost.ai"

    // Privacy controls
    DisableInput  bool  // default: false
    DisableOutput bool  // default: false

    // Performance settings
    EnableRequestQueuing bool           // default: true
    BatchSize            int            // default: 5
    MaxRetries           int            // default: 3
    RetryDelay           time.Duration  // default: 1s
    RequestTimeout       time.Duration  // default: 5s

    // User identification
    Identify IdentifyFunc  // optional

    // Logging
    LogLevel string  // "debug", "info", "warning", "error" (default: "info")
}

Default Config

Use nil to get defaults:

agnost.Track(server, "your-org-id", nil)

Complete Example

package main

import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"

    "github.com/agnostai/agnost-go/agnost"
    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)

func main() {
    // Create MCP server
    s := server.NewMCPServer("example", "1.0.0")

    // Add a tool
    echoTool := mcp.NewTool("echo",
        mcp.WithDescription("Echo a message"),
        mcp.WithString("message", mcp.Required()),
    )

    echoHandler := func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        args := req.Params.Arguments.(map[string]any)
        msg := args["message"].(string)
        return mcp.NewToolResultText(msg), nil
    }

    s.AddTool(echoTool, echoHandler)

    // Track with Agnost
    err := agnost.Track(s, "your-org-id", &agnost.Config{
        DisableInput:  false,
        DisableOutput: false,
        BatchSize:     10,
        LogLevel:      "info",
        Identify: func(req *http.Request, env map[string]string) *agnost.UserIdentity {
            return &agnost.UserIdentity{
                UserID: env["USER_ID"],
                Email:  env["USER_EMAIL"],
            }
        },
    })

    if err != nil {
        log.Printf("Warning: Analytics disabled: %v", err)
    }

    // Graceful shutdown
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)

    go func() {
        <-sigChan
        agnost.Shutdown()
        os.Exit(0)
    }()

    // Start server
    server.ServeStdio(s)
}

API Reference

Functions

Track(server, orgID, config)

Enable analytics tracking for an MCP server.

func Track(s *server.MCPServer, orgID string, config *Config) error

Shutdown()

Gracefully shutdown the analytics client (flushes pending events).

func Shutdown()

Types

Config

Configuration for Agnost Analytics (see Configuration section above)

UserIdentity

type UserIdentity struct {
    UserID string
    Email  string
    Role   string
}

IdentifyFunc

type IdentifyFunc func(req *http.Request, env map[string]string) *UserIdentity

Examples

See the examples directory for complete examples.

Running Examples

cd examples/simple
go run main.go

Performance

• Goroutine-based queuing: Non-blocking event recording
• Batch processing: Reduces API calls by batching events
• Automatic retries: Handles transient failures gracefully
• Minimal overhead: Designed for production use

Development

Build

go build ./...

Test

go test ./...

Format

go fmt ./...

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

License

MIT License - see LICENSE for details.

Support

• Documentation: https://docs.agnost.ai
• Issues: GitHub Issues
• Discord: Join our community

Related Projects

• mcp-go - Go implementation of Model Context Protocol
• Agnost Python SDK - Python SDK for FastMCP and official MCP
• Agnost TypeScript SDK - TypeScript SDK for official MCP

Acknowledgments

Built with ❤️ by the Agnost team. Special thanks to mark3labs for the excellent mcp-go library.