feat: serve the mcp endpoint behind the licence feature

server/internal/api/handlers.go

@@ -8,8 +8,10 @@ import (
 	"strconv"
 
 	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/mcp"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/models"
 	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/services"
+	"gitea.hostxtra.co.uk/vantage/vantage-shared/license"
 	"github.com/gin-gonic/gin"
 )
 
@@ -120,6 +122,14 @@ func RegisterRoutes(r *gin.Engine) {
 		apiGroup.POST("/console/connect", RequireFeature("console"), consoleConnect)
 		apiGroup.GET("/console/tunnel", RequireFeature("console"), consoleTunnel)
 
+		// MCP is mounted inside /api so that bearer auth, rate limiting, licence
+		// activity and RequireScopes all apply from where it lives rather than
+		// because someone remembered. The route-level scope is a floor: one route
+		// serves many tools, so per-tool scopes are enforced inside the handler.
+		mcpGroup := apiGroup.Group("/mcp", RequireFeature(license.FeatureMCP))
+		mcpGroup.POST("", mcp.Handler())
+		mcpGroup.GET("", mcp.Handler())
+
 		registerWorkflowRoutes(apiGroup)
 		registerMonitorRoutes(apiGroup)
 		registerChannelRoutes(apiGroup)

server/internal/api/scopes.go

@@ -43,6 +43,12 @@ var routeScopes = map[string]string{
 	"GET /api/agent/latest-version": "servers:read",
 	"GET /api/audit":                "settings:read",
 
+	// Both MCP routes require mcp:read as a floor. Individual tools require
+	// their own resource scope, and write tools additionally require mcp:write,
+	// enforced inside the handler because one route serves many operations.
+	"POST /api/mcp": "mcp:read",
+	"GET /api/mcp":  "mcp:read",
+
 	"GET /api/settings":                "settings:read",
 	"PUT /api/settings":                "settings:write",
 	"POST /api/settings/secrets-token": "settings:write",

server/internal/api/serverscope.go

@@ -66,6 +66,18 @@ var serverScopedRoutes = map[string]bool{
 	"GET /api/servers/tags": false,
 }
 
+// POST/GET /api/mcp is deliberately absent from this map. main.go's
+// serverTouchingRoutes only feeds in routes whose path contains "server" or
+// "console" (or the one named workflow-run exception), and /api/mcp matches
+// none of those, so it is never presented to AssertServerScopeMapComplete —
+// there is nothing to declare true or false here. That is the right outcome:
+// the single MCP route fronts many tools of very different shapes, several of
+// which touch no server data at all, so a route-level entry could not say
+// anything meaningful about tag scoping. Each tool that does read or act on
+// server data applies auth.ServerScope itself, the same selector the REST
+// handlers for those resources already apply, which is where this kind of
+// scoping decision belongs for a many-operations-per-route endpoint.
+
 // AssertServerScopeMapComplete refuses to boot when a route touching server
 // data is missing from serverScopedRoutes.
 func AssertServerScopeMapComplete(routes []string) error {

server/internal/mcp/transport.go

@@ -0,0 +1,102 @@
+package mcp
+
+import (
+	"context"
+	"errors"
+	"net/http"
+
+	"gitea.hostxtra.co.uk/mrhid6/vantage/server/internal/auth"
+	"github.com/gin-gonic/gin"
+	sdk "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// callerFromContext builds the acting credential from the session the auth
+// middleware already resolved. The mcp package reads no cookie and no header of
+// its own: identity is settled before a request reaches here.
+func callerFromContext(c *gin.Context) Caller {
+	return Caller{
+		InstanceID: auth.InstanceID(c),
+		Scopes:     auth.Scopes(c),
+		TokenScope: auth.ServerScope(c),
+		TokenName:  auth.TokenName(c),
+	}
+}
+
+// Handler serves the MCP endpoint. It is stateless: no session resumption, each
+// request self-contained, which is what lets it sit behind ordinary request
+// middleware with no special casing.
+func Handler() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		caller := callerFromContext(c)
+
+		// A cookie session is not an agent. MCP is a credential-shaped surface
+		// and browsing to it in a logged-in tab must not act as one.
+		if !auth.IsToken(c) {
+			c.AbortWithStatusJSON(http.StatusForbidden, gin.H{
+				"error": "the mcp endpoint requires an API token",
+			})
+			return
+		}
+
+		srv := sdk.NewServer(&sdk.Implementation{
+			Name:    "vantage",
+			Version: buildVersion,
+		}, nil)
+
+		for _, tool := range All().Visible(caller) {
+			registerSDKTool(srv, tool, caller)
+		}
+
+		sdk.NewStreamableHTTPHandler(func(*http.Request) *sdk.Server {
+			return srv
+		}, &sdk.StreamableHTTPOptions{Stateless: true}).ServeHTTP(c.Writer, c.Request)
+	}
+}
+
+// registerSDKTool adapts one registered Tool onto the SDK, wrapping it in the
+// gate check and the audit write. The gate is re-checked here rather than
+// trusted from Visible, because listing and calling are separate requests and a
+// token's scopes are re-read on each.
+func registerSDKTool(srv *sdk.Server, tool Tool, caller Caller) {
+	sdk.AddTool(srv, &sdk.Tool{
+		Name:        tool.Name,
+		Description: tool.Description,
+	}, func(ctx context.Context, req *sdk.CallToolRequest, args map[string]any) (*sdk.CallToolResult, any, error) {
+		if ok, gate := Allowed(tool, caller); !ok {
+			LogDenied(caller, tool.Name, gate)
+			return nil, nil, toolError(gate, tool)
+		}
+
+		out, err := tool.Handler(ctx, caller, args)
+		if err != nil {
+			return nil, nil, err
+		}
+		LogCall(caller, tool, args, 0)
+		return nil, out, nil
+	})
+}
+
+// toolError explains a refusal in words the model can act on. A transport-level
+// failure would be invisible to it; a tool error is something it can read and
+// relay to its user.
+func toolError(gate string, tool Tool) error {
+	switch gate {
+	case GateMCPScope:
+		if tool.Write {
+			return errors.New("this token does not hold mcp:write, so it cannot use tools that change anything")
+		}
+		return errors.New("this token does not hold mcp:read")
+	case GateResourceScope:
+		return errors.New("this token does not hold " + tool.Scope)
+	default:
+		return errors.New("refused")
+	}
+}
+
+// buildVersion is stamped so a user with several instances connected can tell
+// them apart in a client. Wire it to whatever the server already uses for its
+// version string.
+var buildVersion = "dev"
+
+// SetVersion is called once at boot from main.
+func SetVersion(v string) { buildVersion = v }