MCP-Go

https://mcp-go.dev/
Admin
MCP-Go is a Go implementation of the Model Context Protocol that enables seamless integration...
Tokens:97,078
Snippets:424
Trust Score:5.5
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install MCP Go Library

Source: https://mcp-go.dev/getting-started

This snippet shows the command to add the MCP-Go library to your Go project using 'go get'. This is the first step to start building MCP servers.

```go
go get github.com/mark3labs/mcp-go

```

--------------------------------

### Create a Simple MCP Server with a 'hello_world' Tool

Source: https://mcp-go.dev/getting-started

This Go code demonstrates how to create a basic MCP server with a 'hello_world' tool. It includes setting up the server, defining a tool with a string parameter, adding a handler for the tool, and starting the server using stdio transport.

```go
package main
 
import (
    "context"
    "fmt"
 
    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)
 
func main() {
    // Create a new MCP server
    s := server.NewMCPServer(
        "Demo 🚀",
        "1.0.0",
        server.WithToolCapabilities(false),
    )
 
    // Add tool
    tool := mcp.NewTool("hello_world",
        mcp.WithDescription("Say hello to someone"),
        mcp.WithString("name",
            mcp.Required(),
            mcp.Description("Name of the person to greet"),
        ),
    )
 
    // Add tool handler
    s.AddTool(tool, helloHandler)
 
    // Start the stdio server
    if err := server.ServeStdio(s); err != nil {
        fmt.Printf("Server error: %v\n", err)
    }
}
 
func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    name, err := request.RequireString("name")
    if err != nil {
        return mcp.NewToolResultError(err.Error()), nil
    }
 
    return mcp.NewToolResultText(fmt.Sprintf("Hello, %s!", name)), nil
}

```

--------------------------------

### Configure MCP Server with Options

Source: https://mcp-go.dev/getting-started

This Go code demonstrates how to initialize an MCP server with various configuration options. Options shown include enabling tool capabilities, enabling recovery from panics, and adding custom hooks.

```go
s := server.NewMCPServer(
    "My Server",
    "1.0.0",
    server.WithToolCapabilities(true),
    server.WithRecovery(),
    server.WithHooks(myHooks),
)

```

--------------------------------

### Basic MCP Client with Stdio Transport (Go)

Source: https://mcp-go.dev/quick-start

This example demonstrates how to create a basic MCP client in Go using the stdio transport. It connects to a server by executing a Go program, initializes the client, lists available tools, and calls the 'hello_world' tool. Ensure the server's main Go file is accessible at the specified path.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/mark3labs/mcp-go/client"
    "github.com/mark3labs/mcp-go/client/transport"
    "github.com/mark3labs/mcp-go/mcp"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    // Create stdio transport
    stdioTransport := transport.NewStdio("go", nil, "run", "path/to/server/main.go")

    // Create client with the transport
    c := client.NewClient(stdioTransport)

    // Start the client
    if err := c.Start(ctx); err != nil {
        log.Fatalf("Failed to start client: %v", err)
    }
    defer c.Close()

    // Initialize the client
    initRequest := mcp.InitializeRequest{}
    initRequest.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
    initRequest.Params.ClientInfo = mcp.Implementation{
        Name:    "Hello World Client",
        Version: "1.0.0",
    }
    initRequest.Params.Capabilities = mcp.ClientCapabilities{}

    serverInfo, err := c.Initialize(ctx, initRequest)
    if err != nil {
        log.Fatalf("Failed to initialize: %v", err)
    }

    fmt.Printf("Connected to server: %s (version %s)\n",
        serverInfo.ServerInfo.Name,
        serverInfo.ServerInfo.Version)

    // List available tools
    if serverInfo.Capabilities.Tools != nil {
        toolsRequest := mcp.ListToolsRequest{}
        toolsResult, err := c.ListTools(ctx, toolsRequest)
        if err != nil {
            log.Fatalf("Failed to list tools: %v", err)
        }

        fmt.Printf("Available tools: %d\n", len(toolsResult.Tools))
        for _, tool := range toolsResult.Tools {
            fmt.Printf("- %s: %s\n", tool.Name, tool.Description)
        }

        // Call a tool
        callRequest := mcp.CallToolRequest{}
        callRequest.Params.Name = "hello_world"
        callRequest.Params.Arguments = map[string]interface{}{
            "name": "World",
        }

        result, err := c.CallTool(ctx, callRequest)
        if err != nil {
            log.Fatalf("Failed to call tool: %v", err)
        }

        // Print the result
        for _, content := range result.Content {
            if textContent, ok := content.(mcp.TextContent); ok {
                fmt.Printf("Result: %s\n", textContent.Text)
            }
        }
    }
}
```

--------------------------------

### MCP Client with StreamableHTTP Transport (Go)

Source: https://mcp-go.dev/quick-start

This example demonstrates how to create an MCP client in Go using the StreamableHTTP transport. It connects to a server running at a specified URL, initializes the client, and calls the 'hello_world' tool. Ensure the server is accessible at the provided HTTP endpoint.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/mark3labs/mcp-go/client"
    "github.com/mark3labs/mcp-go/client/transport"
    "github.com/mark3labs/mcp-go/mcp"
)

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    // Create HTTP transport
    httpTransport, err := transport.NewStreamableHTTP("http://localhost:8080/mcp")
    if err != nil {
        log.Fatalf("Failed to create HTTP transport: %v", err)
    }

    // Create client with the transport
    c := client.NewClient(httpTransport)
    defer c.Close()

    // Initialize the client
    initRequest := mcp.InitializeRequest{}
    initRequest.Params.ProtocolVersion = mcp.LATEST_PROTOCOL_VERSION
    initRequest.Params.ClientInfo = mcp.Implementation{
        Name:    "StreamableHTTP Client",
        Version: "1.0.0",
    }
    initRequest.Params.Capabilities = mcp.ClientCapabilities{}

    serverInfo, err := c.Initialize(ctx, initRequest)
    if err != nil {
        log.Fatalf("Failed to initialize: %v", err)
    }

    fmt.Printf("Connected to server: %s (version %s)\n",
        serverInfo.ServerInfo.Name,
        serverInfo.ServerInfo.Version)

    // Call a tool
    if serverInfo.Capabilities.Tools != nil {
        callRequest := mcp.CallToolRequest{}
        callRequest.Params.Name = "hello_world"
        callRequest.Params.Arguments = map[string]interface{}{
            "name": "StreamableHTTP World",
        }

        result, err := c.CallTool(ctx, callRequest)
        if err != nil {
            log.Fatalf("Failed to call tool: %v", err)
        }

        fmt.Printf("Tool result: %+v\n", result)
    }
}
```

--------------------------------

### Go MCP Server Example

Source: https://mcp-go.dev/servers

A complete Go program demonstrating the creation and configuration of an MCP server. It includes adding tools, resources, and prompts, and starts the server to listen on stdio. Dependencies include the 'mcp-go' and 'server' packages from 'github.com/mark3labs/mcp-go'.

```go
package main
 
import (
    "context"
    "encoding/json"
    "fmt"
    "time"
 
    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)
 
var start time.Time
 
func main() {
    start = time.Now()
    // Create server with capabilities
    s := server.NewMCPServer(
        "Demo Server",
        "1.0.0",
        server.WithToolCapabilities(true),
        server.WithResourceCapabilities(false, true),
        server.WithPromptCapabilities(true),
    )
 
    // Add a tool
    s.AddTool(
        mcp.NewTool("get_time",
            mcp.WithDescription("Get the current time"),
            mcp.WithString("format", 
                mcp.Description("Time format (RFC3339, Unix, etc.)"),
                mcp.DefaultString("RFC3339"),
            ),
        ),
        handleGetTime,
    )
 
    // Add a resource
    s.AddResource(
        mcp.NewResource(
            "config://server",
            "Server Configuration",
            mcp.WithResourceDescription("Current server configuration"),
            mcp.WithMIMEType("application/json"),
        ),
        handleConfig,
    )
 
    // Add a prompt
    s.AddPrompt(
        mcp.NewPrompt("analyze_logs",
            mcp.WithPromptDescription("Analyze server logs for issues"),
            mcp.WithArgument("log_level",
                mcp.ArgumentDescription("Minimum log level to analyze"),
            ),
        ),
        handleAnalyzeLogs,
    )
 
    // Start the server
    if err := server.ServeStdio(s); err != nil {
        fmt.Printf("Server error: %v\n", err)
    }
}
 
func handleGetTime(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    format := req.GetString("format", "RFC3339")
    
    var timeStr string
    switch format {
    case "Unix":
        timeStr = fmt.Sprintf("%d", time.Now().Unix())
    default:
        timeStr = time.Now().Format(time.RFC3339)
    }
    
    return mcp.NewToolResultText(timeStr), nil
}
 
func handleConfig(ctx context.Context, req mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    config := map[string]interface{}{
        "name": "Demo Server",
        "version": "1.0.0",
        "uptime": time.Since(start).String(),
    }
    
    configJSON, err := json.Marshal(config)
    if err != nil {
        return nil, err
    }
    
    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            URI:      req.Params.URI,
            MIMEType: "application/json",
            Text:     string(configJSON),
        },
    }, nil
}
 
func handleAnalyzeLogs(ctx context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
    logLevel := "error" // default value
    if args := req.Params.Arguments; args != nil {
        if level, ok := args["log_level"].(string); ok {
            logLevel = level
        }
    }
    
    return &mcp.GetPromptResult{
        Description: "Analyze server logs for potential issues",
        Messages: []mcp.PromptMessage{
            {
                Role: mcp.RoleUser,
                Content: mcp.NewTextContent(fmt.Sprintf(
                    "Please analyze the server logs for entries at %s level or higher. " +
                    "Look for patterns, errors, and potential issues that need attention.",
                    logLevel,
                )),
            },
        },
    }, nil
}

```

--------------------------------

### Configure and Start Advanced StreamableHTTP Server (Go)

Source: https://mcp-go.dev/transports/http

Sets up and starts an advanced StreamableHTTP server with various capabilities and middleware. It initializes the MCP server with resource, prompt, and tool capabilities, adds custom tools, and configures the HTTP server with an endpoint path and heartbeat.

```go
func main() {
    s := server.NewMCPServer("Advanced StreamableHTTP Server", "1.0.0",
        server.WithResourceCapabilities(true, true),
        server.WithPromptCapabilities(true),
        server.WithToolCapabilities(true),
        server.WithLogging(),
    )
 
    // Add comprehensive tools and resources
    addCRUDTools(s)
    addBatchTools(s)
    addAnalyticsTools(s)
 
    log.Println("Starting advanced StreamableHTTP server on :8080")
    httpServer := server.NewStreamableHTTPServer(s,
        server.WithEndpointPath("/api/v1/mcp"),
        server.WithHeartbeatInterval(30*time.Second),
        server.WithStateLess(false),
    )
    
    if err := httpServer.Start(":8080"); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Create 'Hello World' MCP Server in Go

Source: https://mcp-go.dev/quick-start

This Go program defines and runs a simple MCP server that hosts a 'hello_world' tool. The tool takes a 'name' argument and returns a greeting. It utilizes the MCP-Go library for server and tool management. Ensure the MCP-Go library is installed.

```go
package main

import (
    "context"
    "fmt"

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

func main() {
    // Create a new MCP server
    s := server.NewMCPServer(
        "Hello World Server",
        "1.0.0",
        server.WithToolCapabilities(true),
    )

    // Define a simple tool
    tool := mcp.NewTool("hello_world",
        mcp.WithDescription("Say hello to someone"),
        mcp.WithString("name",
            mcp.Required(),
            mcp.Description("Name of the person to greet"),
        ),
    )

    // Add tool handler
    s.AddTool(tool, helloHandler)

    // Start the stdio server
    if err := server.ServeStdio(s); err != nil {
        fmt.Printf("Server error: %v\n", err)
    }
}

func helloHandler(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    arguments := request.GetArguments()
    name, ok := arguments["name"].(string)
    if !ok {
        return &mcp.CallToolResult{
            Content: []mcp.Content{
                mcp.TextContent{
                    Type: "text",
                    Text: "Error: name parameter is required and must be a string",
                },
            },
            IsError: true,
        }, nil
    }

    return &mcp.CallToolResult{
        Content: []mcp.Content{
            mcp.TextContent{
                Type: "text",
                Text: fmt.Sprintf("Hello, %s! 👋", name),
            },
        },
    }, nil
}

```

--------------------------------

### Build and Test Sampling Server Integration (Go)

Source: https://mcp-go.dev/clients/advanced-sampling

This snippet demonstrates how to build the sampling server and your client, and then test their integration. It involves navigating to the example directory, building executables, and running the client with the server. Ensure you have Go installed and the necessary project files.

```go
# Build the sampling server
cd examples/sampling_server
go build -o sampling_server
 
# Build your client
go build -o my_client
 
# Test the integration
./my_client ./sampling_server
```

--------------------------------

### Run MCP Server with MCP Inspector

Source: https://mcp-go.dev/quick-start

This shell command demonstrates how to use the MCP Inspector tool to run and test an MCP server. First, it installs the inspector globally using npm. Then, it executes the Go server through the inspector, which provides a web interface for interactive testing.

```shell
# Install the MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run your server with the inspector
mcp-inspector go run main.go

```

--------------------------------

### Start MCP Server with Streamable HTTP Transport

Source: https://mcp-go.dev/getting-started

This Go snippet illustrates how to start an MCP server using the StreamableHTTP transport method, listening on a specified port.

```go
server.NewStreamableHTTPServer(s).Start(":8080")

```

--------------------------------

### Complete MCP Client Lifecycle Example (Go)

Source: https://mcp-go.dev/clients/basics

Demonstrates the full lifecycle of an MCP client in Go, from creation and initialization to operation and cleanup. This example highlights the importance of proper error handling and resource management using `defer` for closing the client.

```Go
func demonstrateClientLifecycle() error {
    // 1. Creation
    c, err := client.NewSSEMCPClient("server-command")
    if err != nil {
        return fmt.Errorf("client creation failed: %w", err)
    }
 
    // Ensure cleanup happens
    defer func() {
        if closeErr := c.Close(); closeErr != nil {
            log.Printf("Error closing client: %v", closeErr)
        }
    }()
 
    ctx := context.Background()
 
    // 2. Initialization
    if err := c.Initialize(ctx); err != nil {
        return fmt.Errorf("client initialization failed: %w", err)
    }
 
    // 3. Operation
    if err := performClientOperations(ctx, c); err != nil {
        return fmt.Errorf("client operations failed: %w", err)
    }
 
    // 4. Cleanup (handled by defer)
    return nil
}
 
func performClientOperations(ctx context.Context, c client.Client) error {
    // List available tools
    tools, err := c.ListTools(ctx)
    if err != nil {
        return err
    }
 
    log.Printf("Found %d tools", len(tools.Tools))
 
    // Use the tools
    for _, tool := range tools.Tools {
        result, err := c.CallTool(ctx, mcp.CallToolRequest{
            Params: mcp.CallToolRequestParams{
                Name:      tool.Name,
                Arguments: map[string]interface{}{
                    "input": "example input",
                    "format": "json",
                },
            },
        })
        if err != nil {
            log.Printf("Tool %s failed: %v", tool.Name, err)
            continue
        }
 
        log.Printf("Tool %s result: %+v", tool.Name, result)
    }
 
    return nil
}
```

--------------------------------

### Go Example: Custom StreamableHTTP Server with Endpoints

Source: https://mcp-go.dev/transports/http

Demonstrates how to create a custom StreamableHTTP server in Go, integrating standard MCP endpoints with custom API routes for status, metrics, users, and file uploads. It includes setting up routes, adding middleware, and starting the server.

```go
func main() {
    s := server.NewMCPServer("Custom StreamableHTTP Server", "1.0.0")
    
    // Create HTTP server with custom routes
    mux := http.NewServeMux()
    
    // Add MCP endpoints
    mux.Handle("/mcp", server.NewStreamableHTTPServer(s))
    
    // Add custom endpoints
    mux.HandleFunc("/api/status", handleStatus)
    mux.HandleFunc("/api/metrics", handleMetrics)
    mux.HandleFunc("/api/users", handleUsersAPI)
    mux.HandleFunc("/api/upload", handleFileUpload)
    
    // Add middleware
    handler := addMiddleware(mux)
    
    log.Println("Starting custom StreamableHTTP server on :8080")
    if err := http.ListenAndServe(":8080", handler); err != nil {
        log.Fatal(err)
    }
}
 
func handleStatus(w http.ResponseWriter, r *http.Request) {
    status := map[string]interface{}{
        "status":    "healthy",
        "timestamp": time.Now().Unix(),
        "version":   "1.0.0",
        "uptime":    time.Since(startTime).String(),
    }
    
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(status)
}
 
func handleMetrics(w http.ResponseWriter, r *http.Request) {
    metrics := collectMetrics()
    
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(metrics)
}
 
func handleUsersAPI(w http.ResponseWriter, r *http.Request) {
    switch r.Method {
    case "GET":
        handleListUsers(w, r)
    case "POST":
        handleCreateUserAPI(w, r)
    case "PUT":
        handleUpdateUser(w, r)
    case "DELETE":
        handleDeleteUser(w, r)
    default:
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
    }
}
```

--------------------------------

### Complete Production Server Setup in Go

Source: https://mcp-go.dev/servers/advanced

This Go code demonstrates the setup of a complete production server for MCP. It includes initialization of logging, metrics, session management, and notification components. Middleware for logging, rate limiting, and authentication are configured, along with telemetry and business hooks. The server is configured with various capabilities and then started with graceful shutdown handling.

```go
func main() {
    // Initialize components
    logger := log.New(os.Stdout, "[MCP] ", log.LstdFlags)
    metrics := NewPrometheusMetrics()
    sessionManager := NewSessionManager()
    notifier := NewCustomNotifier()
    
    // Create middleware
    loggingMW := NewLoggingMiddleware(logger)
    rateLimitMW := NewRateLimitMiddleware(10.0, 20) // 10 req/sec, burst 20
    authMW := NewAuthMiddleware(NewJWTValidator())
    
    // Create hooks
    telemetryHooks := NewTelemetryHooks(metrics, logger)
    businessHooks := NewBusinessHooks(NewAuditLogger(), NewSlackNotifier())
    
    // Create server with all features
    s := server.NewMCPServer("Production Server", "1.0.0",
        server.WithToolCapabilities(true),
        server.WithResourceCapabilities(false, true),
        server.WithPromptCapabilities(true),
        server.WithRecovery(),
        server.WithHooks(telemetryHooks),
        server.WithToolHandlerMiddleware(loggingMW.ToolMiddleware),
        server.WithToolFilter(NewPermissionFilter(sessionManager)),
    )
    
    // Add tools and resources
    addProductionTools(s)
    addProductionResources(s)
    addProductionPrompts(s)
    
    // Start server with graceful shutdown
    startWithGracefulShutdown(s)
}
 
func startWithGracefulShutdown(s *server.MCPServer) {
    // Setup signal handling
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
    
    // Start server in goroutine
    go func() {
        if err := server.ServeStdio(s); err != nil {
            log.Printf("Server error: %v", err)
        }
    }()
    
    // Wait for shutdown signal
    <-sigChan
    log.Println("Shutting down server...")
    
    // Graceful shutdown with timeout
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    
    if err := s.Shutdown(ctx); err != nil {
        log.Printf("Shutdown error: %v", err)
    }
    
    log.Println("Server stopped")
}
```

--------------------------------

### Go Example: Stateless Tool Handling

Source: https://mcp-go.dev/transports/http

Provides a Go code example for handling tool calls in a stateless manner. It demonstrates extracting necessary information from the request context and parameters, processing it independently of server state, and returning a result.

```go
// Each request is independent
func handleStatelessTool(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // Extract all needed information from request
    userID := extractUserFromToken(ctx)
    params := req.Params.Arguments
    
    // Process without relying on server state
    result, err := processRequest(userID, params)
    if err != nil {
        return nil, err
    }
    
    return mcp.NewToolResultJSON(result)
}
 
// Use external storage for persistence
func getUserPreferences(userID string) (map[string]interface{}, error) {
    // Load from database, cache, etc.
    return loadFromRedis(fmt.Sprintf("user:%s:prefs", userID))
}
```

--------------------------------

### Go: Initialize and Start StreamableHTTP Server

Source: https://mcp-go.dev/transports/http

Initializes and starts a StreamableHTTP server using mcp-go. It configures the server with tools and resources, and then begins listening for incoming HTTP requests on port 8080. Dependencies include the 'net/http', 'log', and custom 'github.com/mark3labs/mcp-go/server' packages.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "net/http"
    "strings"
    "time"

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

func main() {
    s := server.NewMCPServer("StreamableHTTP API Server", "1.0.0",
        server.WithToolCapabilities(true),
        server.WithResourceCapabilities(true, true),
    )

    // Add RESTful tools
    s.AddTool(
        mcp.NewTool("get_user",
            mcp.WithDescription("Get user information"),
            mcp.WithString("user_id", mcp.Required()),
        ),
        handleGetUser,
    )

    s.AddTool(
        mcp.NewTool("create_user",
            mcp.WithDescription("Create a new user"),
            mcp.WithString("name", mcp.Required()),
            mcp.WithString("email", mcp.Required()),
            mcp.WithNumber("age", mcp.Min(0)),
        ),
        handleCreateUser,
    )

    s.AddTool(
        mcp.NewTool("search_users",
            mcp.WithDescription("Search users with filters"),
            mcp.WithString("query", mcp.Description("Search query")),
            mcp.WithNumber("limit", mcp.DefaultNumber(10), mcp.Max(100)),
            mcp.WithNumber("offset", mcp.DefaultNumber(0), mcp.Min(0)),
        ),
        handleSearchUsers,
    )

    // Add resources
    s.AddResource(
        mcp.NewResource(
            "users://{user_id}",
            "User Profile",
            mcp.WithResourceDescription("User profile data"),
            mcp.WithMIMEType("application/json"),
        ),
        handleUserResource,
    )

    // Start StreamableHTTP server
    log.Println("Starting StreamableHTTP server on :8080")
    httpServer := server.NewStreamableHTTPServer(s)
    if err := httpServer.Start(":8080"); err != nil {
        log.Fatal(err)
    }
}

func handleGetUser(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    userID := req.GetString("user_id", "")
    if userID == "" {
        return nil, fmt.Errorf("user_id is required")
    }
    
    // Simulate database lookup
    user, err := getUserFromDB(userID)
    if err != nil {
        return nil, fmt.Errorf("user not found: %s", userID)
    }

    return mcp.NewToolResultText(fmt.Sprintf(`{"id":"%s","name":"%s","email":"%s","age":%d}`, 
        user.ID, user.Name, user.Email, user.Age)), nil
}

func handleCreateUser(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    name := req.GetString("name", "")
    email := req.GetString("email", "")
    age := req.GetInt("age", 0)

    if name == "" || email == "" {
        return nil, fmt.Errorf("name and email are required")
    }

    // Validate input
    if !isValidEmail(email) {
        return nil, fmt.Errorf("invalid email format: %s", email)
    }

    // Create user
    user := &User{
        ID:        generateID(),
        Name:      name,
        Email:     email,
        Age:       age,
        CreatedAt: time.Now(),
    }

    if err := saveUserToDB(user); err != nil {
        return nil, fmt.Errorf("failed to create user: %w", err)
    }

    return mcp.NewToolResultText(fmt.Sprintf(`{"id":"%s","message":"User created successfully","user":{"id":"%s","name":"%s","email":"%s","age":%d}}`,
        user.ID, user.ID, user.Name, user.Email, user.Age)), nil
}

// Helper functions and types for the examples
type User struct {
    ID        string    `json:"id"`
    Name      string    `json:"name"`
    Email     string    `json:"email"`
    Age       int       `json:"age"`
    CreatedAt time.Time `json:"created_at"`
}

func getUserFromDB(userID string) (*User, error) {
    // Placeholder implementation
    return &User{
        ID:    userID,
        Name:  "John Doe",
        Email: "john@example.com",
        Age:   30,
    }, nil
}

func isValidEmail(email string) bool {
    return strings.Contains(email, "@") && strings.Contains(email, ".")
}

func generateID() string {
    // Placeholder implementation
    return fmt.Sprintf("user_%d", time.Now().UnixNano())
}

func saveUserToDB(user *User) error {
    // Placeholder implementation
    return nil
}

func handleSearchUsers(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    query := req.GetString("query", "")
    limit := req.GetInt("limit", 10)
    offset := req.GetInt("offset", 0)

    // Search users with pagination
    users, total, err := searchUsersInDB(query, limit, offset)
    if err != nil {
        return nil, fmt.Errorf("search failed: %w", err)
    }

    return mcp.NewToolResultText(fmt.Sprintf(`{"users":[{"id":"1","name":"John Doe","email":"john@example.com","age":30},{"id":"2","name":"Jane Smith","email":"jane@example.com","age":25}],"total":%d,"limit":%d,"offset":%d,"query":"%s"}`,
        total, limit, offset, query)), nil
}

func handleUserResource(ctx context.Context, req mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    userID := extractUserIDFromURI(req.Params.URI)
    
    // Placeholder for actual resource fetching logic
    return []mcp.ResourceContents{
        {
            Data: []byte(`{
                "id": "` + userID + `",
                "name": "John Doe",
                "email": "john@example.com",
                "age": 30
            }`),
            MIMEType: "application/json",
        },
    }, nil
}

func extractUserIDFromURI(uri string) string {
    // Placeholder implementation to extract user ID from URI
    parts := strings.Split(uri, "//")
    if len(parts) > 1 {
        return strings.TrimPrefix(parts[1], "{")
    }
    return ""
}

// Mock database functions (replace with actual database logic)
func searchUsersInDB(query string, limit, offset int) ([]*User, int, error) {
    // Placeholder implementation
    allUsers := []*User{
        {ID: "1", Name: "John Doe", Email: "john@example.com", Age: 30, CreatedAt: time.Now()},
        {ID: "2", Name: "Jane Smith", Email: "jane@example.com", Age: 25, CreatedAt: time.Now()},
        {ID: "3", Name: "Peter Jones", Email: "peter@example.com", Age: 40, CreatedAt: time.Now()},
    }
    
    // Simple filtering based on query (case-insensitive)
    var filteredUsers []*User
    if query == "" {
        filteredUsers = allUsers
    } else {
        for _, u := range allUsers {
            if strings.Contains(strings.ToLower(u.Name), strings.ToLower(query)) || strings.Contains(strings.ToLower(u.Email), strings.ToLower(query)) {
                filteredUsers = append(filteredUsers, u)
            }
        }
    }

    total := len(filteredUsers)
    
    // Apply pagination
    start := offset
    end := offset + limit
    if start > total {
        start = total
    }
    if end > total {
        end = total
    }
    
    paginatedUsers := []*User{}
    if start < end {
        paginatedUsers = filteredUsers[start:end]
    }

    return paginatedUsers, total, nil
}

```

--------------------------------

### Go: Basic SSE Server with MCP-Go

Source: https://mcp-go.dev/transports/sse

Sets up an SSE server using MCP-Go, registering tools for streaming data and system monitoring, and a resource for current metrics. It starts the SSE server on port 8080 and handles client requests and notifications.

```go
package main

import (
    "context"
    "fmt"
    "log"
    "time"

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

func main() {
    s := server.NewMCPServer("SSE Server", "1.0.0",
        server.WithToolCapabilities(true),
        server.WithResourceCapabilities(true, true),
    )

    // Add real-time tools
    s.AddTool(
        mcp.NewTool("stream_data",
            mcp.WithDescription("Stream data with real-time updates"),
            mcp.WithString("source", mcp.Required()),
            mcp.WithNumber("count", mcp.DefaultNumber(10)),
        ),
        handleStreamData,
    )

    s.AddTool(
        mcp.NewTool("monitor_system",
            mcp.WithDescription("Monitor system metrics in real-time"),
            mcp.WithNumber("duration", mcp.DefaultNumber(60)),
        ),
        handleSystemMonitor,
    )

    // Add dynamic resources
    s.AddResource(
        mcp.NewResource(
            "metrics://current",
            "Current System Metrics",
            mcp.WithResourceDescription("Real-time system metrics"),
            mcp.WithMIMEType("application/json"),
        ),
        handleCurrentMetrics,
    )

    // Start SSE server
    log.Println("Starting SSE server on :8080")
    sseServer := server.NewSSEServer(s)
    if err := sseServer.Start(":8080"); err != nil {
        log.Fatal(err)
    }
}

func handleStreamData(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // Access request headers
    headers := req.Header

    // Use headers for authentication, tracing, etc.
    authToken := headers.Get("Authorization")
    if authToken == "" {
        return nil, fmt.Errorf("authentication required")
    }
    
    // Access other headers
    requestID := headers.Get("X-Request-ID")
    userAgent := headers.Get("User-Agent")
    
    source := req.GetString("source", "")
    count := req.GetInt("count", 10)

    // Get server from context for notifications
    mcpServer := server.ServerFromContext(ctx)

    // Stream data with progress updates
    var results []map[string]interface{}
    for i := 0; i < count; i++ {
        // Check for cancellation
        select {
        case <-ctx.Done():
            return nil, ctx.Err()
        default:
        }

        // Simulate data processing
        data := generateData(source, i)
        results = append(results, data)

        // Send progress notification
        if mcpServer != nil {
            err := mcpServer.SendNotificationToClient(ctx, "notifications/progress", map[string]interface{}{
                "progress": i + 1,
                "total":    count,
                "message":  fmt.Sprintf("Processed %d/%d items from %s", i+1, count, source),
            })
            if err != nil {
                log.Printf("Failed to send notification: %v", err)
            }
        }

        time.Sleep(100 * time.Millisecond)
    }

    return mcp.NewToolResultText(fmt.Sprintf(`{"source":"%s","results":%v,"count":%d}`,
        source, results, len(results))), nil
}

// Helper functions for the examples
func generateData(source string, index int) map[string]interface{} {
    return map[string]interface{}{
        "source": source,
        "index":  index,
        "value":  fmt.Sprintf("data_%d", index),
    }
}

func handleSystemMonitor(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    duration := req.GetInt("duration", 60)
    
    mcpServer := server.ServerFromContext(ctx)

    // Monitor system for specified duration
    ticker := time.NewTicker(5 * time.Second)
    defer ticker.Stop()

    timeout := time.After(time.Duration(duration) * time.Second)
    var metrics []map[string]interface{}

    for {
        select {
        case <-ctx.Done():
            return nil, ctx.Err()
        case <-timeout:
            return mcp.NewToolResultText(fmt.Sprintf(`{"duration":%d,"metrics":%v,"samples":%d}`,
                duration, metrics, len(metrics))), nil
        case <-ticker.C:
            // Collect current metrics
            currentMetrics := collectSystemMetrics()
            metrics = append(metrics, currentMetrics)

            // Send real-time update
            if mcpServer != nil {
                err := mcpServer.SendNotificationToClient(ctx, "system_metrics", currentMetrics)
                if err != nil {
                    log.Printf("Failed to send system metrics notification: %v", err)
                }
            }
        }
    }
}

func collectSystemMetrics() map[string]interface{} {
    // Placeholder implementation
    return map[string]interface{}{
        "cpu":    50.5,
        "memory": 75.2,
        "disk":   30.1,
    }
}

func handleCurrentMetrics(ctx context.Context, req mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    metrics := collectSystemMetrics()
    return []mcp.ResourceContents{
        mcp.TextResourceContents{
            Content: fmt.Sprintf("{\"cpu\": %.1f, \"memory\": %.1f, \"disk\": %.1f}", metrics["cpu"], metrics["memory"], metrics["disk"]),
            MIMEType: "application/json",
        },
    }, nil
}

```

--------------------------------

### Start MCP Server with HTTP Transport in Go

Source: https://mcp-go.dev/servers/basics

Demonstrates how to initialize and start an MCP server using the HTTP transport. This involves creating an `httpServer` instance and binding it to a specific port, making it suitable for web services and APIs.

```go
func main() {
    s := server.NewMCPServer("HTTP Server", "1.0.0")
    
    // Create HTTP server
    httpServer := server.NewStreamableHTTPServer(s)
    
    // Start HTTP server on port 8080
    if err := httpServer.Start(":8080"); err != nil {
        log.Fatal(err)
    }
}
```

--------------------------------

### Create Basic MCP Server in Go

Source: https://mcp-go.dev/servers/basics

Demonstrates the creation of a fundamental MCP server instance using `NewMCPServer` and starting it with the stdio transport. This is the entry point for most MCP server applications.

```go
package main
 
import (
    "github.com/mark3labs/mcp-go/server"
)
 
func main() {
    // Create a basic server
    s := server.NewMCPServer(
        "My MCP Server",  // Server name
        "1.0.0",          // Server version
    )
    
    // Start the server (stdio transport)
    server.ServeStdio(s)
}
```

--------------------------------

### Test STDIO Server from Command Line in Go

Source: https://mcp-go.dev/transports/stdio

Provides commands to test a Go STDIO server directly from the command line. This involves starting the server and then piping JSON-RPC requests to its standard input to simulate client interactions.

```bash
# Start your server
go run main.go

# Send initialization request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"clientInfo":{"name":"test","version":"1.0.0"}}}' | go run main.go

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | go run main.go

# Call a tool
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_files","arguments":{"path":".","recursive":false}}}' | go run main.go

```

--------------------------------

### Complete MCP Go Server Example with Sampling

Source: https://mcp-go.dev/servers/advanced-sampling

A comprehensive example of an MCP Go server that enables and utilizes the sampling capability. It demonstrates server initialization, adding a sampling tool, handling requests, and managing responses, including error scenarios and timeouts.

```go
package main
 
import (
    "context"
    "fmt"
    "log"
    "time"
    
    "github.com/mark3labs/mcp-go/mcp"
    "github.com/mark3labs/mcp-go/server"
)
 
func main() {
    // Create server
    mcpServer := server.NewMCPServer("sampling-example-server", "1.0.0")
    
    // Enable sampling capability
    mcpServer.EnableSampling()
    
    // Add sampling tool
    mcpServer.AddTool(mcp.Tool{
        Name:        "ask_llm",
        Description: "Ask the LLM a question using sampling",
        InputSchema: mcp.ToolInputSchema{
            Type: "object",
            Properties: map[string]any{
                "question": map[string]any{
                    "type":        "string",
                    "description": "The question to ask the LLM",
                },
                "system_prompt": map[string]any{
                    "type":        "string",
                    "description": "Optional system prompt",
                },
            },
            Required: []string{"question"},
        },
    }, func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        question, err := request.RequireString("question")
        if err != nil {
            return nil, err
        }
        
        systemPrompt := request.GetString("system_prompt", "You are a helpful assistant.")
        
        // Create sampling request
        samplingRequest := mcp.CreateMessageRequest{
            CreateMessageParams: mcp.CreateMessageParams{
                Messages: []mcp.SamplingMessage{
                    {
                        Role: mcp.RoleUser,
                        Content: mcp.TextContent{
                            Type: "text",
                            Text: question,
                        },
                    },
                },
                SystemPrompt: systemPrompt,
                MaxTokens:    1000,
                Temperature:  0.7,
            },
        }
        
        // Request sampling with timeout
        samplingCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
        defer cancel()
        
        result, err := mcpServer.RequestSampling(samplingCtx, samplingRequest)
        if err != nil {
            return &mcp.CallToolResult{
                Content: []mcp.Content{
                    mcp.TextContent{
                        Type: "text",
                        Text: fmt.Sprintf("Error requesting sampling: %v", err),
                    },
                },
                IsError: true,
            }, nil
        }
        
        // Return the LLM response
        return &mcp.CallToolResult{
            Content: []mcp.Content{
                mcp.TextContent{
                    Type: "text",
                    Text: fmt.Sprintf("LLM Response (model: %s): %s", 
                        result.Model, getTextFromContent(result.Content)),
                },
            },
        }, nil
    })
    
    // Start server
    log.Println("Starting sampling example server...")
    if err := server.ServeStdio(mcpServer); err != nil {
        log.Fatalf("Server error: %v", err)
    }
}
 
// Helper function to extract text from content
func getTextFromContent(content interface{}) string {
    switch c := content.(type) {
    case mcp.TextContent:
        return c.Text
    case string:
        return c
    default:
        return fmt.Sprintf("%v", content)
    }
}
```

--------------------------------

### Start MCP Server with Server-Sent Events Transport

Source: https://mcp-go.dev/getting-started

This Go snippet shows how to initiate an MCP server using the Server-Sent Events (SSE) transport, binding to a specific network interface and port.

```go
server.ServeSSE(s, ":8080")

```

--------------------------------

### Create and Use an MCP Client (Go)

Source: https://mcp-go.dev/clients

Demonstrates creating a STDIO MCP client, initializing it, and performing operations such as listing tools and resources, calling a tool, and reading a resource. This example requires the 'context', 'fmt', 'log', and MCP-Go client libraries.

```go
package main
 
import (
    "context"
    "fmt"
    "log"
 
    "github.com/mark3labs/mcp-go/client"
    "github.com/mark3labs/mcp-go/mcp"
)
 
func main() {
    // Create STDIO client
    c, err := client.NewStdioMCPClient(
        "go", []string{} , "run", "/path/to/server/main.go",
    )
    if err != nil {
        log.Fatal(err)
    }
    defer c.Close()
 
    ctx := context.Background()
 
    // Initialize the connection
    if err := c.Initialize(ctx, initRequest); err != nil {
        log.Fatal(err)
    }
 
    // Discover available capabilities
    if err := demonstrateClientOperations(ctx, c); err != nil {
        log.Fatal(err)
    }
}
 
func demonstrateClientOperations(ctx context.Context, c client.Client) error {
    // List available tools
    tools, err := c.ListTools(ctx)
    if err != nil {
        return fmt.Errorf("failed to list tools: %w", err)
    }
 
    fmt.Printf("Available tools: %d\n", len(tools.Tools))
    for _, tool := range tools.Tools {
        fmt.Printf("- %s: %s\n", tool.Name, tool.Description)
    }
 
    // List available resources
    resources, err := c.ListResources(ctx)
    if err != nil {
        return fmt.Errorf("failed to list resources: %w", err)
    }
 
    fmt.Printf("\nAvailable resources: %d\n", len(resources.Resources))
    for _, resource := range resources.Resources {
        fmt.Printf("- %s: %s\n", resource.URI, resource.Name)
    }
 
    // Call a tool if available
    if len(tools.Tools) > 0 {
        tool := tools.Tools[0]
        fmt.Printf("\nCalling tool: %s\n", tool.Name)
 
        result, err := c.CallTool(ctx, mcp.CallToolRequest{
            Params: mcp.CallToolRequestParams{
                Name: tool.Name,
                Arguments: map[string]interface{}{
                    "input": "example input",
                    "format": "text",
                },
            },
        })
        if err != nil {
            return fmt.Errorf("tool call failed: %w", err)
        }
 
        fmt.Printf("Tool result: %+v\n", result)
    }
 
    // Read a resource if available
    if len(resources.Resources) > 0 {
        resource := resources.Resources[0]
        fmt.Printf("\nReading resource: %s\n", resource.URI)
 
        content, err := c.ReadResource(ctx, mcp.ReadResourceRequest{
            Params: mcp.ReadResourceRequestParams{
                URI: resource.URI,
            },
        })
        if err != nil {
            return fmt.Errorf("resource read failed: %w", err)
        }
 
        fmt.Printf("Resource content: %+v\n", content)
    }
 
    return nil
}

```
Tokens:
Raw