Skip to main content
This guide shows how to integrate Agnost analytics with your Go MCP server using the mcp-go library.

Step 1: Install Dependencies

go get github.com/mark3labs/mcp-go
go get github.com/agnostai/agnost-go/agnost

Step 2: Import Required Packages

import (
    "context"
    "log"

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

Step 3: Create Your Server

// Create the MCP server
s := server.NewMCPServer(
    "My Analytics Server",
    "1.0.0",
    server.WithToolCapabilities(true),
)

Step 4: Define Your Tools

Add your tool handlers:
// Add echo tool
echoTool := mcp.NewTool("echo",
    mcp.WithDescription("Echo back a message"),
    mcp.WithString("message", mcp.Required(), mcp.Description("Message to echo")),
)

echoHandler := func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    args, ok := request.Params.Arguments.(map[string]any)
    if !ok {
        return mcp.NewToolResultError("Invalid arguments"), nil
    }

    message, _ := args["message"].(string)
    return mcp.NewToolResultText("Echo: " + message), nil
}

s.AddTool(echoTool, echoHandler)

// Add calculator tool
calcTool := mcp.NewTool("add",
    mcp.WithDescription("Add two numbers together"),
    mcp.WithNumber("a", mcp.Required(), mcp.Description("First number")),
    mcp.WithNumber("b", mcp.Required(), mcp.Description("Second number")),
)

calcHandler := func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    args, ok := request.Params.Arguments.(map[string]any)
    if !ok {
        return mcp.NewToolResultError("Invalid arguments"), nil
    }

    a, _ := args["a"].(float64)
    b, _ := args["b"].(float64)
    result := a + b

    return mcp.NewToolResultText(fmt.Sprintf("%.2f", result)), nil
}

s.AddTool(calcTool, calcHandler)

Step 5: Add Analytics

Enable analytics tracking with your organization ID:
// Add analytics with your org_id from https://app.agnost.ai
err := agnost.Track(s, "your-org-id-here", &agnost.Config{
    Endpoint: "https://api.agnost.ai",
    DisableInput: false,
    DisableOutput: false,
    LogLevel: "info",
})

if err != nil {
    log.Printf("Warning: Failed to enable analytics: %v", err)
}

With Custom Configuration

err := agnost.Track(s, "your-org-id-here", &agnost.Config{
    // API endpoint
    Endpoint: "https://api.agnost.ai",

    // Privacy controls
    DisableInput:  false,
    DisableOutput: false,

    // Performance settings
    EnableRequestQueuing: true,
    BatchSize:            5,
    MaxRetries:           3,
    RetryDelay:           1 * time.Second,
    RequestTimeout:       5 * time.Second,

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

With User Identification

err := agnost.Track(s, "your-org-id-here", &agnost.Config{
    Endpoint: "https://api.agnost.ai",

    // User identification
    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"],
        }
    },
})

Step 6: Start Your Server

func main() {
    // ... server setup and tools ...

    // Start server on stdio
    log.Println("Starting MCP server...")
    if err := server.ServeStdio(s); err != nil {
        log.Fatalf("Server error: %v", err)
    }
}

Complete Example

Here’s a complete working example:
package main

import (
    "context"
    "fmt"
    "log"
    "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(
        "Go Example Server",
        "1.0.0",
        server.WithToolCapabilities(true),
    )

    // Add echo tool
    addEchoTool(s)

    // Add calculator tool
    addCalculatorTool(s)

    // Add greeter tool
    addGreetTool(s)

    // Configure Agnost Analytics
    orgID := "your-org-id-here" // Replace with your org ID

    err := agnost.Track(s, orgID, &agnost.Config{
        Endpoint:      "https://api.agnost.ai",
        DisableInput:  false,
        DisableOutput: false,
        LogLevel:      "info",
    })

    if err != nil {
        log.Printf("Warning: Failed to enable analytics: %v", err)
    } else {
        log.Println("✓ Agnost Analytics enabled")
    }

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

    go func() {
        <-sigChan
        log.Println("\nShutting down...")
        agnost.Shutdown()
        os.Exit(0)
    }()

    // Start server
    log.Println("Starting MCP server...")
    if err := server.ServeStdio(s); err != nil {
        log.Fatalf("Server error: %v", err)
    }
}

func addEchoTool(s *server.MCPServer) {
    echoTool := mcp.NewTool("echo",
        mcp.WithDescription("Echo back a message"),
        mcp.WithString("message", mcp.Required(), mcp.Description("Message to echo")),
    )

    echoHandler := func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        args, ok := request.Params.Arguments.(map[string]any)
        if !ok {
            return mcp.NewToolResultError("Invalid arguments"), nil
        }

        message, _ := args["message"].(string)
        return mcp.NewToolResultText("Echo: " + message), nil
    }

    s.AddTool(echoTool, echoHandler)
}

func addCalculatorTool(s *server.MCPServer) {
    calcTool := mcp.NewTool("add",
        mcp.WithDescription("Add two numbers together"),
        mcp.WithNumber("a", mcp.Required(), mcp.Description("First number")),
        mcp.WithNumber("b", mcp.Required(), mcp.Description("Second number")),
    )

    calcHandler := func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        args, ok := request.Params.Arguments.(map[string]any)
        if !ok {
            return mcp.NewToolResultError("Invalid arguments"), nil
        }

        a, aOk := args["a"].(float64)
        b, bOk := args["b"].(float64)

        if !aOk || !bOk {
            return mcp.NewToolResultError("Both arguments must be numbers"), nil
        }

        result := a + b
        return mcp.NewToolResultText(fmt.Sprintf("%.2f", result)), nil
    }

    s.AddTool(calcTool, calcHandler)
}

func addGreetTool(s *server.MCPServer) {
    greetTool := mcp.NewTool("greet",
        mcp.WithDescription("Greet a user by name"),
        mcp.WithString("name", mcp.Required(), mcp.Description("Name to greet")),
        mcp.WithString("greeting", mcp.Description("Custom greeting (optional, default: 'Hello')")),
    )

    greetHandler := func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        args, ok := request.Params.Arguments.(map[string]any)
        if !ok {
            return mcp.NewToolResultError("Invalid arguments"), nil
        }

        name, _ := args["name"].(string)
        greeting, _ := args["greeting"].(string)

        if greeting == "" {
            greeting = "Hello"
        }

        return mcp.NewToolResultText(greeting + ", " + name + "!"), nil
    }

    s.AddTool(greetTool, greetHandler)
}

Building and Running

Create go.mod

go mod init my-mcp-server
go mod tidy

Build

go build -o server main.go

Run

./server

Configuration Options

OptionTypeDefaultDescription
Endpointstring"https://api.agnost.ai"API endpoint URL for analytics data
DisableInputboolfalseWhether to disable tracking of input parameters
DisableOutputboolfalseWhether to disable tracking of output responses
EnableRequestQueuingbooltrueEnable background event queuing
BatchSizeint5Number of events to batch before sending
MaxRetriesint3Maximum retry attempts for failed requests
RetryDelaytime.Duration1 * time.SecondDelay between retry attempts
RequestTimeouttime.Duration5 * time.SecondTimeout for HTTP requests
IdentifyfuncnilFunction to identify users from request context
LogLevelstring"info"Logging level (debug, info, warning, error)

Troubleshooting

Build errors?
  • Ensure you have Go 1.21+ installed: go version
  • Run go mod tidy to download dependencies
  • Check that import paths are correct
Server not starting?
  • Verify your server is using server.ServeStdio(s) correctly
  • Check for compilation errors: go build
  • Ensure no port conflicts
No analytics data?
  • Verify your organization ID is correct from app.agnost.ai
  • Check that the Agnost API endpoint is accessible
  • Look for error messages in your server logs
  • Increase log level to "debug" for more details
Import errors?
  • Update Agnost: go get -u github.com/agnostai/agnost-go/agnost
  • Update mcp-go: go get -u github.com/mark3labs/mcp-go
  • Run go mod tidy to clean up dependencies

Next Steps

I