{"id":30867043,"url":"https://github.com/traego/scaled-mcp","last_synced_at":"2026-01-12T02:43:25.434Z","repository":{"id":286899566,"uuid":"962726343","full_name":"Traego/scaled-mcp","owner":"Traego","description":"ScaledMCP is a horizontally scalabled MCP and A2A Server. You know, for AI.","archived":false,"fork":false,"pushed_at":"2025-08-11T00:59:34.000Z","size":487,"stargazers_count":39,"open_issues_count":5,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-11T02:36:02.838Z","etag":null,"topics":["a2a","ai","mcp","mcp-client","mcp-server"],"latest_commit_sha":null,"homepage":"https://scaledmcp.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Traego.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-08T15:24:59.000Z","updated_at":"2025-08-11T00:59:02.000Z","dependencies_parsed_at":"2025-07-12T23:24:27.265Z","dependency_job_id":"6a38b4be-c7a1-43b8-8dbf-b89b6b09556d","html_url":"https://github.com/Traego/scaled-mcp","commit_stats":null,"previous_names":["traego/scaled-mcp"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/Traego/scaled-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traego%2Fscaled-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traego%2Fscaled-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traego%2Fscaled-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traego%2Fscaled-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Traego","download_url":"https://codeload.github.com/Traego/scaled-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Traego%2Fscaled-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274101814,"owners_count":25222452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","ai","mcp","mcp-client","mcp-server"],"created_at":"2025-09-07T22:03:23.505Z","updated_at":"2026-01-12T02:43:25.382Z","avatar_url":"https://github.com/Traego.png","language":"Go","funding_links":[],"categories":["🤖 AI/ML"],"sub_categories":[],"readme":"# Scaled MCP Server\n\n[![CI Status](https://github.com/traego/scaled-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/traego/scaled-mcp/actions/workflows/ci.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/traego/scaled-mcp.svg)](https://pkg.go.dev/github.com/traego/scaled-mcp)\n[![Go Report Card](https://img.shields.io/badge/go%20report-A+-brightgreen.svg?style=flat)](https://goreportcard.com/report/github.com/traego/scaled-mcp)\n[![codecov](https://codecov.io/gh/traego/scaled-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/traego/scaled-mcp)\n[![License](https://img.shields.io/github/license/traego/scaled-mcp)](https://github.com/traego/scaled-mcp/blob/main/LICENSE)\n\nA horizontally scalable MCP (Message Context Protocol) server implementation that supports load-balanced deployments.\n\n## Overview\n\nThe Scaled MCP Server is a Go library that implements the MCP 2025-03 specification with support for horizontal scaling. It's designed to be embedded in your application and provides flexible configuration options.\n\n## Features\n\n- **HTTP Transport**: Flexible HTTP transport with main `/mcp` endpoint, optional SSE endpoint, and capabilities negotiation\n- **Session Management**: Distributed session management with Redis or in-memory options\n- **Actor System**: Uses an actor-based architecture for handling sessions and message routing\n- **Horizontal Scaling**: Support for load-balanced deployments across multiple nodes\n\n## Installation\n\n```bash\ngo get github.com/traego/scaled-mcp@latest\n```\n\n\u003e **Note:** This library requires Go 1.24 or higher.\n\n## Usage\n\n### Basic Server with Static Tool\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log/slog\"\n\t\"os\"\n\t\"os/signal\"\n\t\"syscall\"\n\n\t\"github.com/traego/scaled-mcp/pkg/config\"\n\t\"github.com/traego/scaled-mcp/pkg/resources\"\n\t\"github.com/traego/scaled-mcp/pkg/server\"\n)\n\nfunc main() {\n\t// Configure logging\n\tlogHandler := slog.NewTextHandler(os.Stdout, \u0026slog.HandlerOptions{Level: slog.LevelDebug})\n\tslog.SetDefault(slog.New(logHandler))\n\n\t// Create a server with default configuration\n\tcfg := config.DefaultConfig()\n\t\n\t// Use in-memory session store for simplicity\n\tcfg.Session.UseInMemory = true\n\t\n\t// Create a static tool registry\n\tregistry := resources.NewStaticToolRegistry()\n\t\n\t// Define and register a simple calculator tool\n\tcalculatorTool := resources.NewTool(\"calculator\").\n\t\tWithDescription(\"Performs basic arithmetic operations\").\n\t\tWithInputs([]resources.ToolInput{\n\t\t\t{\n\t\t\t\tName:        \"operation\",\n\t\t\t\tType:        \"string\",\n\t\t\t\tDescription: \"Operation to perform (add, subtract, multiply, divide)\",\n\t\t\t\tRequired:    true,\n\t\t\t},\n\t\t\t{\n\t\t\t\tName:        \"a\",\n\t\t\t\tType:        \"number\",\n\t\t\t\tDescription: \"First operand\",\n\t\t\t\tRequired:    true,\n\t\t\t},\n\t\t\t{\n\t\t\t\tName:        \"b\",\n\t\t\t\tType:        \"number\",\n\t\t\t\tDescription: \"Second operand\",\n\t\t\t\tRequired:    true,\n\t\t\t},\n\t\t}).\n\t\tBuild()\n\t\n\t// Register the tool with the registry\n\tregistry.RegisterTool(calculatorTool)\n\t\n\t// Define a prompt for the server\n\tprompt := \"You are a helpful AI assistant that can perform calculations using the calculator tool.\"\n\t\n\t// Create the server with the tool registry and prompt\n\tsrv, err := server.NewMcpServer(cfg,\n\t\tserver.WithToolRegistry(registry),\n\t\tserver.WithServerInfo(\"Example MCP Server\", \"1.0.0\"),\n\t\tserver.WithPrompt(prompt),\n\t)\n\tif err != nil {\n\t\tslog.Error(\"Failed to create server\", \"error\", err)\n\t\tos.Exit(1)\n\t}\n\t\n\t// Set up the tool handler\n\tregistry.SetToolHandler(\"calculator\", func(ctx context.Context, params map[string]interface{}) (interface{}, error) {\n\t\t// Extract parameters\n\t\toperation, ok := params[\"operation\"].(string)\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"%w: operation must be a string\", resources.ErrInvalidParams)\n\t\t}\n\t\t\n\t\ta, ok := params[\"a\"].(float64)\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"%w: a must be a number\", resources.ErrInvalidParams)\n\t\t}\n\t\t\n\t\tb, ok := params[\"b\"].(float64)\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"%w: b must be a number\", resources.ErrInvalidParams)\n\t\t}\n\t\t\n\t\t// Perform the calculation\n\t\tvar result float64\n\t\tswitch operation {\n\t\tcase \"add\":\n\t\t\tresult = a + b\n\t\tcase \"subtract\":\n\t\t\tresult = a - b\n\t\tcase \"multiply\":\n\t\t\tresult = a * b\n\t\tcase \"divide\":\n\t\t\tif b == 0 {\n\t\t\t\treturn nil, fmt.Errorf(\"%w: division by zero\", resources.ErrInvalidParams)\n\t\t\t}\n\t\t\tresult = a / b\n\t\tdefault:\n\t\t\treturn nil, fmt.Errorf(\"%w: unknown operation %s\", resources.ErrInvalidParams, operation)\n\t\t}\n\t\t\n\t\treturn map[string]interface{}{\n\t\t\t\"result\": result,\n\t\t}, nil\n\t})\n\t\n\t// Start the server in a goroutine\n\tgo func() {\n\t\tif err := srv.Start(context.Background()); err != nil {\n\t\t\tslog.Error(\"Failed to start server\", \"error\", err)\n\t\t\tos.Exit(1)\n\t\t}\n\t}()\n\t\n\tslog.Info(\"Server started\", \"host\", cfg.HTTP.Host, \"port\", cfg.HTTP.Port)\n\t\n\t// Wait for termination signal\n\tsig := make(chan os.Signal, 1)\n\tsignal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)\n\t\u003c-sig\n\t\n\t// Shutdown the server\n\tslog.Info(\"Shutting down server...\")\n\tshutdownCtx, cancel := context.WithTimeout(context.Background(), cfg.HTTP.ShutdownTimeout)\n\tdefer cancel()\n\t\n\tif err := srv.Stop(shutdownCtx); err != nil {\n\t\tslog.Error(\"Failed to stop server\", \"error\", err)\n\t}\n\t\n\tslog.Info(\"Server stopped\")\n}\n\n### Using an External HTTP Server\n\nYou can use your own HTTP server with the MCP transport:\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"log\"\n\t\"net/http\"\n\n\t\"github.com/go-chi/chi/v5\"\n\t\"github.com/go-chi/chi/v5/middleware\"\n\t\"github.com/go-chi/cors\"\n\t\"github.com/traego/scaled-mcp/pkg/config\"\n\t\"github.com/traego/scaled-mcp/pkg/server\"\n\t\"github.com/traego/scaled-mcp/pkg/transport\"\n)\n\nfunc main() {\n\t// Create a server with default configuration\n\tcfg := config.DefaultConfig()\n\tcfg.Session.UseInMemory = true\n\t\n\t// Create the MCP server but don't start the HTTP server\n\tsrv, err := server.NewServer(cfg)\n\tif err != nil {\n\t\tlog.Fatalf(\"Failed to create server: %v\", err)\n\t}\n\t\n\t// Create a custom router\n\tr := chi.NewRouter()\n\t\n\t// Add middleware\n\tr.Use(middleware.RequestID)\n\tr.Use(middleware.RealIP)\n\tr.Use(middleware.Logger)\n\tr.Use(middleware.Recoverer)\n\t\n\t// Add CORS middleware - important when using an external server\n\tr.Use(cors.Handler(cors.Options{\n\t\tAllowedOrigins:   []string{\"*\"},\n\t\tAllowedMethods:   []string{\"GET\", \"POST\", \"PUT\", \"DELETE\", \"OPTIONS\"},\n\t\tAllowedHeaders:   []string{\"Accept\", \"Authorization\", \"Content-Type\", \"X-CSRF-Token\"},\n\t\tExposedHeaders:   []string{\"Link\"},\n\t\tAllowCredentials: true,\n\t\tMaxAge:           300,\n\t}))\n\t\n\t// Add your custom routes\n\tr.Get(\"/\", func(w http.ResponseWriter, r *http.Request) {\n\t\tw.Write([]byte(\"Welcome to the MCP server!\"))\n\t})\n\t\n\t// Create the HTTP transport with the custom router\n\thttpTransport := transport.NewHTTPTransport(\n\t\tcfg,\n\t\tsrv.GetActorSystem(),\n\t\tsrv.GetSessionManager(),\n\t\ttransport.WithExternalRouter(r),\n\t)\n\t\n\t// Start the MCP server without HTTP\n\tif err := srv.Start(context.Background()); err != nil {\n\t\tlog.Fatalf(\"Failed to start server: %v\", err)\n\t}\n\t\n\t// Start the HTTP transport\n\tif err := httpTransport.Start(); err != nil {\n\t\tlog.Fatalf(\"Failed to start HTTP transport: %v\", err)\n\t}\n\t\n\t// Start your HTTP server\n\tlog.Printf(\"Starting HTTP server on %s:%d\", cfg.HTTP.Host, cfg.HTTP.Port)\n\tif err := http.ListenAndServe(\":8080\", r); err != nil {\n\t\tlog.Fatalf(\"HTTP server error: %v\", err)\n\t}\n}\n\n## Dynamic Tool Registry Example\n\nThis library supports both static and dynamic tool registries. Here's an client_example of using a dynamic tool registry:\n\n```go\n// Create a custom tool provider\ntoolProvider := NewExampleToolProvider()\n\n// Create a dynamic tool registry with the provider\nregistry := resources.NewDynamicToolRegistry(toolProvider)\n\n// Create server with the dynamic tool registry\ncfg := config.DefaultConfig()\nmcpServer, err := server.NewMcpServer(cfg,\n    server.WithToolRegistry(registry),\n)\n```\n\n### Tool Definition\n\nThe library provides three ways to define tool inputs:\n\n#### 1. Using Struct-Based Reflection (Recommended)\n\n```go\n// Define input struct with mcp tags\ntype CalculatorInput struct {\n    Operation string  `mcp:\"operation,The operation to perform (add subtract multiply divide),required\"`\n    A         float64 `mcp:\"a,First operand,required\"`\n    B         float64 `mcp:\"b,Second operand,required\"`\n}\n\n// Type-safe handler function\nfunc calculatorHandler(ctx context.Context, input *CalculatorInput) (interface{}, error) {\n    // Direct access to typed fields: input.Operation, input.A, input.B\n    switch input.Operation {\n    case \"add\":\n        return map[string]interface{}{\"result\": input.A + input.B}, nil\n    // ...\n    }\n}\n\n// Register with automatic schema generation (method 1)\ncalculatorType := reflect.TypeOf(CalculatorInput{})\nregistry.RegisterStructToolWithHandler(\"calculator\", \"Performs arithmetic operations\", calculatorType, calculatorHandler)\n\n// Or use the convenience function (method 2)\nresources.RegisterStructTool(registry, \"calculator\", \"Performs arithmetic operations\", calculatorHandler)\n\n### Generics-Based Tool Registration (New in June 2025)\n\nFor even better type safety, you can use the new generics-based approach with two type parameters for input and output:\n\n```go\ntype CalculatorInput struct {\n    Operation string  `mcp:\"operation,The operation to perform,required\"`\n    A         float64 `mcp:\"a,First operand,required\"`\n    B         float64 `mcp:\"b,Second operand,required\"`\n}\n\ntype CalculatorOutput struct {\n    Result    float64 `mcp:\"result,The calculation result,required\"`\n    Operation string  `mcp:\"operation,The operation performed,required\"`\n}\n\nfunc calculatorHandler(ctx context.Context, input *CalculatorInput) (*CalculatorOutput, error) {\n    result := input.A + input.B\n    return \u0026CalculatorOutput{\n        Result:    result,\n        Operation: input.Operation,\n    }, nil\n}\n\n// Register with compile-time type safety for both input and output\nerr := resources.RegisterStructToolWithTypes(registry, \"calculator\", \"Performs arithmetic\", calculatorHandler)\n```\n\nThis approach provides:\n- **Compile-time type safety** for both input and output\n- **Automatic schema generation** for both input and output types\n- **Zero reflection** at registration time (uses generics instead)\n- **Better IDE support** with full type checking\n\n\n```\n\n#### 2. Using WithInputs\n\n```go\nweatherTool := resources.NewTool(\"weather\").\n    WithDescription(\"Get weather information for a location\").\n    WithInputs([]resources.ToolInput{\n        {\n            Name:        \"location\",\n            Type:        \"string\",\n            Description: \"The location to get weather for\",\n            Required:    true,\n        },\n        {\n            Name:        \"units\",\n            Type:        \"string\",\n            Description: \"Temperature units (celsius or fahrenheit)\",\n            Default:     \"celsius\",\n        },\n    }).\n    Build()\n```\n\n#### 3. Using Individual Parameter Methods\n\n```go\ncalculatorTool := resources.NewTool(\"calculator\").\n    WithDescription(\"Performs basic arithmetic operations\").\n    WithString(\"operation\").\n    Required().\n    Description(\"Operation to perform (add, subtract, multiply, divide)\").\n    Add().\n    WithNumber(\"a\").\n    Required().\n    Description(\"First operand\").\n    Add().\n    WithNumber(\"b\").\n    Required().\n    Description(\"Second operand\").\n    Add().\n    Build()\n```\n\n### Struct Tag Format\n\nThe `mcp` struct tag follows the format: `mcp:\"name,description,required,default=value\"`\n\n- **name**: Field name in the schema (defaults to lowercase field name)\n- **description**: Human-readable description of the field\n- **required**: Mark field as required\n- **default=value**: Set a default value for optional fields\n- **-**: Skip field (not included in schema)\n\n**Supported Go Types:**\n- `string` → `\"string\"`\n- `int`, `int64`, etc. → `\"integer\"`\n- `float64`, `float32` → `\"number\"`\n- `bool` → `\"boolean\"`\n- `[]T`, `[N]T` → `\"array\"`\n- `struct`, `map` → `\"object\"`\n- `*T` → Same as `T` (pointer types)\n\n## Important Notes\n\n### CORS Configuration\n\nWhen using an external HTTP server with the MCP transport, you need to configure CORS settings on your router. The MCP transport will not apply CORS settings when using an external router, as shown in the example above.\n\n### Session Management\n\nFor production deployments, it's recommended to use Redis for session management to support horizontal scaling. The in-memory session store should only be used for development or testing.\n\n## To Do\n- [ ] Authorization Examples + Auth Context Flow Through\n- [ ] Metrics endpoint (prometheus), covering actor starts / stops, avg session length, etc\n- [ ] Session Actor Hooks\n- [ ] MCP Spec\n  - [ ] List Change Notifications\n  - [ ] Sampling\n  - [ ] Roots\n  - [ ] Completion\n  - [ ] Logging\n- [ ] A2A Spec\n  - [ ] Added details here https://github.com/Traego/scaled-mcp/wiki/A2A-Support\n- [ ] Pipelining to support plugins\n- [ ] K8S Clustering Hooked Up + Tested\n- [ ] Search support (https://github.com/modelcontextprotocol/modelcontextprotocol/pull/322)\n- [ ] Full testing of all features (resources, prompts, etc.)\n- [ ] Test Coverage to 80%\n- [ ] Cleanup New Server API just a bit to make it easier to standup\n- [ ] Better defaults\n- [ ] Get to vNext of goakt and replace custom messaging schedule (was a bug workaround)\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Development\n\n### Testing\n\nRun tests:\n\n```bash\ngo test ./...\n```\n\nRun tests with coverage:\n\n```bash\ngo test -race -coverprofile=coverage.txt -covermode=atomic ./...\n```\n\nView coverage report in browser:\n\n```bash\ngo tool cover -html=coverage.txt\n```\n\n### Code Coverage\n\nThis project uses [Codecov](https://codecov.io/) for code coverage reporting. Coverage reports are automatically generated and uploaded during CI runs.\n\nTo view the coverage dashboard, visit [codecov.io/gh/traego/scaled-mcp](https://codecov.io/gh/traego/scaled-mcp).\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n## Documentation\n\nSee the [GoDoc](https://pkg.go.dev/github.com/traego/scaled-mcp) for detailed API documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraego%2Fscaled-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftraego%2Fscaled-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftraego%2Fscaled-mcp/lists"}