MCP Server and Its Implementation with Go

// data/reports.json
{
  "reports": [
    {
      "id": "rpt-001",
      "title": "Q1 2025 Financial Report",
      "department": "finance",
      "period": "Q1 2025",
      "created_at": "2025-01-15T08:00:00Z",
      "created_by": "[email protected]",
      "status": "published",
      "summary": "Q1 total revenue reached Rp 4.2 billion, up 12% from Q4 2024.",
      "figures": {
        "revenue": 4200000000,
        "expenses": 2800000000,
        "net_profit": 1400000000,
        "growth_pct": 12.4
      }
    },
    {
      "id": "rpt-002",
      "title": "Q2 2025 Financial Report",
      "department": "finance",
      "period": "Q2 2025",
      "created_at": "2025-04-10T09:30:00Z",
      "created_by": "[email protected]",
      "status": "published",
      "summary": "Growth slowed in Q2 due to rising operational costs.",
      "figures": {
        "revenue": 4050000000,
        "expenses": 3100000000,
        "net_profit": 950000000,
        "growth_pct": -3.6
      }
    },
    {
      "id": "rpt-003",
      "title": "H1 2025 Operations Report",
      "department": "operations",
      "period": "H1 2025",
      "created_at": "2025-07-01T10:00:00Z",
      "created_by": "[email protected]",
      "status": "draft",
      "summary": "Production efficiency improved 8% thanks to the new system implementation.",
      "figures": {
        "efficiency_pct": 8.2,
        "downtime_hours": 24,
        "output_units": 125000,
        "defect_rate_pct": 0.8
      }
    },
    {
      "id": "rpt-004",
      "title": "Q2 HR Report",
      "department": "hr",
      "period": "Q2 2025",
      "created_at": "2025-04-20T14:00:00Z",
      "created_by": "[email protected]",
      "status": "published",
      "summary": "Employee retention rate 94%, recruited 23 new positions.",
      "figures": {
        "headcount": 312,
        "new_hires": 23,
        "resignations": 18,
        "retention_pct": 94.2
      }
    }
  ]
}

// internal/store/reports.go
package store

import (
	"encoding/json"
	"fmt"
	"os"
	"sync"
	"time"
)

// Report represents one report in the system
type Report struct {
	ID         string                 `json:"id"`
	Title      string                 `json:"title"`
	Department string                 `json:"department"`
	Period     string                 `json:"period"`
	CreatedAt  time.Time              `json:"created_at"`
	CreatedBy  string                 `json:"created_by"`
	Status     string                 `json:"status"`
	Summary    string                 `json:"summary"`
	Figures    map[string]interface{} `json:"figures"`
}

type database struct {
	Reports []Report `json:"reports"`
}

// ReportStore manages read-write operations to the backend service
type ReportStore struct {
	path string
	mu   sync.RWMutex
}

func NewReportStore(path string) *ReportStore {
	return &ReportStore{path: path}
}

func (s *ReportStore) load() (*database, error) {
	data, err := os.ReadFile(s.path)
	if err != nil {
		return nil, fmt.Errorf("failed to read file: %w", err)
	}
	var db database
	if err := json.Unmarshal(data, &db); err != nil {
		return nil, fmt.Errorf("failed to parse JSON: %w", err)
	}
	return &db, nil
}

func (s *ReportStore) save(db *database) error {
	data, err := json.MarshalIndent(db, "", "  ")
	if err != nil {
		return fmt.Errorf("failed to encode JSON: %w", err)
	}
	return os.WriteFile(s.path, data, 0644)
}

// GetAll returns all reports
func (s *ReportStore) GetAll() ([]Report, error) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	db, err := s.load()
	if err != nil {
		return nil, err
	}
	return db.Reports, nil
}

// GetByID returns a report by ID
func (s *ReportStore) GetByID(id string) (*Report, error) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	db, err := s.load()
	if err != nil {
		return nil, err
	}
	for _, r := range db.Reports {
		if r.ID == id {
			return &r, nil
		}
	}
	return nil, fmt.Errorf("report with ID '%s' not found", id)
}

// GetByDepartment returns reports by department
func (s *ReportStore) GetByDepartment(dept string) ([]Report, error) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	db, err := s.load()
	if err != nil {
		return nil, err
	}
	var result []Report
	for _, r := range db.Reports {
		if r.Department == dept {
			result = append(result, r)
		}
	}
	return result, nil
}

// Delete removes a report by ID
func (s *ReportStore) Delete(id string) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	db, err := s.load()
	if err != nil {
		return err
	}
	newReports := make([]Report, 0, len(db.Reports))
	found := false
	for _, r := range db.Reports {
		if r.ID == id {
			found = true
			continue
		}
		newReports = append(newReports, r)
	}
	if !found {
		return fmt.Errorf("report with ID '%s' not found", id)
	}
	db.Reports = newReports
	return s.save(db)
}

// internal/auth/jwt.go
package auth

import (
	"context"
	"fmt"
	"strings"
	"time"

	"github.com/MicahParks/keyfunc/v2"
	"github.com/golang-jwt/jwt/v5"
)

// Claims represents the JWT payload from Authentik
type Claims struct {
	Sub            string   `json:"sub"`
	Email          string   `json:"email"`
	Name           string   `json:"name"`
	MCPPermissions []string `json:"mcp_permissions"`
	Department     string   `json:"department"`
	jwt.RegisteredClaims
}

// Validator validates JWTs using the JWKS from Authentik
type Validator struct {
	jwks *keyfunc.JWKS
}

// NewValidator creates a new Validator connected to Authentik's JWKS endpoint
func NewValidator(jwksURL string) (*Validator, error) {
	jwks, err := keyfunc.Get(jwksURL, keyfunc.Options{
		RefreshInterval: time.Hour,
		RefreshErrorHandler: func(err error) {
			// Log the JWKS refresh error — don't crash the server
			fmt.Printf("JWKS refresh error: %v\n", err)
		},
	})
	if err != nil {
		return nil, fmt.Errorf("failed to initialize JWKS from %s: %w", jwksURL, err)
	}
	return &Validator{jwks: jwks}, nil
}

// Validate validates a token string and returns the claims if valid
func (v *Validator) Validate(tokenStr string) (*Claims, error) {
	if tokenStr == "" {
		return nil, fmt.Errorf("token must not be empty")
	}

	claims := &Claims{}
	token, err := jwt.ParseWithClaims(tokenStr, claims, v.jwks.Keyfunc)
	if err != nil {
		return nil, fmt.Errorf("invalid token: %w", err)
	}
	if !token.Valid {
		return nil, fmt.Errorf("token expired or invalid")
	}

	return claims, nil
}

// ExtractFromContext takes the Bearer token from the MCP context
// The MCP client sends the token via the Authorization: Bearer *** header
func ExtractFromContext(ctx context.Context) (string, error) {
	// mcp-go stores the authorization header in the context with this key
	authHeader, ok := ctx.Value("authorization").(string)
	if !ok || authHeader == "" {
		return "", fmt.Errorf("Authorization header not found in request")
	}

	const prefix = "Bearer "
	if !strings.HasPrefix(authHeader, prefix) {
		return "", fmt.Errorf("Authorization format must be 'Bearer <token>'")
	}

	token := strings.TrimPrefix(authHeader, prefix)
	if token == "" {
		return "", fmt.Errorf("token is empty after Bearer prefix")
	}

	return token, nil
}

// internal/rbac/policy.go
package rbac

import "fmt"

// toolPermissions defines the permission required by each tool.
// This is the only place to change when you add a new tool
// or change access rules.
var toolPermissions = map[string]string{
	"list_reports":  "report:read",
	"get_report":    "report:read",
	"delete_report": "report:delete",
}

// Check verifies whether the user's permission list includes the
// permission required for the requested tool.
func Check(toolName string, userPermissions []string) error {
	required, exists := toolPermissions[toolName]
	if !exists {
		// Tool not registered in the policy — deny as a safety measure
		return fmt.Errorf("tool '%s' is not registered in the policy", toolName)
	}

	for _, p := range userPermissions {
		if p == required {
			return nil // ✓ Access granted
		}
	}

	return fmt.Errorf(
		"access denied: tool '%s' requires permission '%s'",
		toolName, required,
	)
}

// RequiredPermission returns the permission required by a tool.
// Useful for informative error messages.
func RequiredPermission(toolName string) string {
	if p, ok := toolPermissions[toolName]; ok {
		return p
	}
	return "unknown"
}

// CORRECT: always register a permission for every new tool
"create_report": "report:write",

// ANTI-PATTERN: leaving a tool without a policy entry
// Result: "tool not registered in the policy" → automatic 403
// This is actually safe behavior, but explicit is better

// internal/tools/get_report.go
package tools

import (
	"context"
	"encoding/json"
	"fmt"

	"github.com/kamu/mcp-reports/internal/auth"
	"github.com/kamu/mcp-reports/internal/rbac"
	"github.com/kamu/mcp-reports/internal/store"
	"github.com/mark3labs/mcp-go/mcp"
)

// ReportTools wraps all report-related tools
type ReportTools struct {
	store     *store.ReportStore
	validator *auth.Validator
}

func NewReportTools(s *store.ReportStore, v *auth.Validator) *ReportTools {
	return &ReportTools{store: s, validator: v}
}

// checkAccess is an internal helper that does the auth + RBAC check.
// All tools call this as their first step.
func (t *ReportTools) checkAccess(ctx context.Context, toolName string) (*auth.Claims, error) {
	tokenStr, err := auth.ExtractFromContext(ctx)
	if err != nil {
		return nil, fmt.Errorf("unauthorized: %w", err)
	}

	claims, err := t.validator.Validate(tokenStr)
	if err != nil {
		return nil, fmt.Errorf("unauthorized: %w", err)
	}

	if err := rbac.Check(toolName, claims.MCPPermissions); err != nil {
		return nil, err // The error message from RBAC is already descriptive
	}

	return claims, nil
}

// HandleListReports returns all available reports.
// Requires permission: report:read
func (t *ReportTools) HandleListReports(
	ctx context.Context,
	req mcp.CallToolRequest,
) (*mcp.CallToolResult, error) {
	claims, err := t.checkAccess(ctx, "list_reports")
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}

	// Get the optional filter from arguments
	deptFilter, _ := req.Params.Arguments["department"].(string)

	var reports []store.Report
	if deptFilter != "" {
		reports, err = t.store.GetByDepartment(deptFilter)
	} else {
		reports, err = t.store.GetAll()
	}
	if err != nil {
		return mcp.NewToolResultError(fmt.Sprintf("failed to fetch data: %v", err)), nil
	}

	// Create a summary for each report (don't expose detailed figures)
	type reportSummary struct {
		ID         string `json:"id"`
		Title      string `json:"title"`
		Department string `json:"department"`
		Period     string `json:"period"`
		Status     string `json:"status"`
		CreatedBy  string `json:"created_by"`
	}

	summaries := make([]reportSummary, len(reports))
	for i, r := range reports {
		summaries[i] = reportSummary{
			ID:         r.ID,
			Title:      r.Title,
			Department: r.Department,
			Period:     r.Period,
			Status:     r.Status,
			CreatedBy:  r.CreatedBy,
		}
	}

	data, _ := json.MarshalIndent(map[string]interface{}{
		"total":       len(summaries),
		"reports":     summaries,
		"accessed_by": claims.Email,
	}, "", "  ")

	return mcp.NewToolResultText(string(data)), nil
}

// HandleGetReport returns the complete details of one report by ID.
// Requires permission: report:read
func (t *ReportTools) HandleGetReport(
	ctx context.Context,
	req mcp.CallToolRequest,
) (*mcp.CallToolResult, error) {
	claims, err := t.checkAccess(ctx, "get_report")
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}

	reportID, ok := req.Params.Arguments["report_id"].(string)
	if !ok || reportID == "" {
		return mcp.NewToolResultError("the 'report_id' parameter is required"), nil
	}

	report, err := t.store.GetByID(reportID)
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}

	data, _ := json.MarshalIndent(map[string]interface{}{
		"report":      report,
		"accessed_by": claims.Email,
		"accessed_at": "now",
	}, "", "  ")

	return mcp.NewToolResultText(string(data)), nil
}

// internal/tools/delete_report.go
package tools

import (
	"context"
	"fmt"

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

// HandleDeleteReport permanently deletes a report from the JSON file.
// Requires permission: report:delete (admin role only)
func (t *ReportTools) HandleDeleteReport(
	ctx context.Context,
	req mcp.CallToolRequest,
) (*mcp.CallToolResult, error) {
	// RBAC check — only report:delete permission can reach this point
	claims, err := t.checkAccess(ctx, "delete_report")
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}

	reportID, ok := req.Params.Arguments["report_id"].(string)
	if !ok || reportID == "" {
		return mcp.NewToolResultError("the 'report_id' parameter is required"), nil
	}

	// Verify the report exists before deleting it
	report, err := t.store.GetByID(reportID)
	if err != nil {
		return mcp.NewToolResultError(err.Error()), nil
	}

	if err := t.store.Delete(reportID); err != nil {
		return mcp.NewToolResultError(fmt.Sprintf("failed to delete: %v", err)), nil
	}

	result := fmt.Sprintf(
		"Report '%s' (%s) successfully deleted by %s.",
		report.Title, report.ID, claims.Email,
	)

	return mcp.NewToolResultText(result), nil
}

// config/config.go
package config

import (
	"fmt"
	"os"
)

// Config stores all MCP server runtime configuration
type Config struct {
	// AuthentikJWKSURL is the JWKS endpoint URL of the OAuth2 provider in Authentik
	// Example: https://auth.company.com/application/o/mcp-reports/jwks/
	AuthentikJWKSURL string

	// DataPath is the path to the JSON file storing report data
	DataPath string

	// ServerPort is the HTTP port where the MCP server listens for connections
	ServerPort string

	// ServerBaseURL is the MCP server's public URL, used by the SSE transport
	ServerBaseURL string
}

// Load reads configuration from environment variables and validates it
func Load() (*Config, error) {
	cfg := &Config{
		AuthentikJWKSURL: getEnv("AUTHENTIK_JWKS_URL", ""),
		DataPath:         getEnv("DATA_PATH", "./data/reports.json"),
		ServerPort:       getEnv("SERVER_PORT", "3000"),
		ServerBaseURL:    getEnv("SERVER_BASE_URL", "http://localhost:3000"),
	}

	if cfg.AuthentikJWKSURL == "" {
		return nil, fmt.Errorf("AUTHENTIK_JWKS_URL is required")
	}

	return cfg, nil
}

func getEnv(key, fallback string) string {
	if v := os.Getenv(key); v != "" {
		return v
	}
	return fallback
}

// main.go
package main

import (
	"fmt"
	"log"

	"github.com/kamu/mcp-reports/config"
	"github.com/kamu/mcp-reports/internal/auth"
	"github.com/kamu/mcp-reports/internal/store"
	"github.com/kamu/mcp-reports/internal/tools"
	"github.com/mark3labs/mcp-go/mcp"
	"github.com/mark3labs/mcp-go/server"
)

func main() {
	// 1. Load configuration from the environment
	cfg, err := config.Load()
	if err != nil {
		log.Fatalf("Invalid configuration: %v", err)
	}

	// 2. Initialize the JWT validator connected to Authentik JWKS
	validator, err := auth.NewValidator(cfg.AuthentikJWKSURL)
	if err != nil {
		log.Fatalf("Failed to initialize JWT validator: %v", err)
	}

	// 3. Initialize the store reading data from the JSON file
	reportStore := store.NewReportStore(cfg.DataPath)

	// 4. Create the tool handler instance
	reportTools := tools.NewReportTools(reportStore, validator)

	// 5. Create the MCP server with metadata
	s := server.NewMCPServer(
		"Report MCP Server",
		"1.0.0",
		server.WithToolCapabilities(true),
	)

	// 6. Register the list_reports tool with its input schema
	s.AddTool(
		mcp.NewTool("list_reports",
			mcp.WithDescription(
				"Lists all available reports. "+
					"Use the 'department' filter to narrow results. "+
					"Requires the report:read permission.",
			),
			mcp.WithString("department",
				mcp.Description("Filter by department (finance, operations, hr). Leave empty for all departments."),
			),
		),
		reportTools.HandleListReports,
	)

	// 7. Register the get_report tool
	s.AddTool(
		mcp.NewTool("get_report",
			mcp.WithDescription(
				"Returns the complete details of one report by ID, "+
					"including financial or operational figures. "+
					"Use list_reports first to get a valid ID. "+
					"Requires the report:read permission.",
			),
			mcp.WithString("report_id",
				mcp.Required(),
				mcp.Description("Report ID in the 'rpt-XXX' format, e.g. rpt-001"),
			),
		),
		reportTools.HandleGetReport,
	)

	// 8. Register the delete_report tool (admin only)
	s.AddTool(
		mcp.NewTool("delete_report",
			mcp.WithDescription(
				"Permanently deletes a report from the system. "+
					"THIS ACTION CANNOT BE UNDONE. "+
					"Only available to users with the report:delete permission (admin role). "+
					"Use get_report first to verify the report to be deleted.",
			),
			mcp.WithString("report_id",
				mcp.Required(),
				mcp.Description("ID of the report to delete in the 'rpt-XXX' format"),
			),
		),
		reportTools.HandleDeleteReport,
	)

	// 9. Run the server using SSE transport
	addr := fmt.Sprintf(":%s", cfg.ServerPort)
	httpServer := server.NewSSEServer(s,
		server.WithBaseURL(cfg.ServerBaseURL),
	)

	log.Printf("MCP Report Server running at %s", cfg.ServerBaseURL)
	log.Printf("SSE endpoint: %s/sse", cfg.ServerBaseURL)
	log.Printf("Data source: %s", cfg.DataPath)

	if err := httpServer.Start(addr); err != nil {
		log.Fatalf("Server failed: %v", err)
	}
}

# Development — using a local Authentik
export AUTHENTIK_JWKS_URL="https://authentik.local/application/o/mcp-reports/jwks/"
export DATA_PATH="./data/reports.json"
export SERVER_PORT="3000"
export SERVER_BASE_URL="http://localhost:3000"

go run ./main.go

# Test list_reports (needs a valid JWT from Authentik)
curl -X POST http://localhost:3000/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <JWT_FROM_AUTHENTIK>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_reports",
      "arguments": {}
    }
  }'

# Property Mapping in Authentik (Python expression)
# Mapping name: "MCP Report Permissions"
# Scope name: "mcp"

user_groups = [g.name for g in request.user.ak_groups.all()]

permissions = []

# Admin gets all permissions
if "mcp-admin" in user_groups:
    permissions = ["report:read", "report:delete"]

# Finance and Managers can only read
elif any(g in user_groups for g in ["finance", "manager", "analyst"]):
    permissions = ["report:read"]

# Regular users get no MCP permissions
# (the token stays valid but all tool calls will be denied)

return permissions

# Property Mapping: "MCP Department"
# Scope name: "mcp"

# Take the department from the user attributes in Authentik
return request.user.attributes.get("department", "")

{
  "sub": "user-abc123",
  "email": "[email protected]",
  "mcp_permissions": ["report:read"],
  "department": "finance",
  "exp": 1234567890
}

{
  "sub": "user-xyz789",
  "email": "[email protected]",
  "mcp_permissions": ["report:read", "report:delete"],
  "department": "it",
  "exp": 1234567890
}