feat(mcp): only register read-only tools in read-only mode

When read_only is enabled, the MCP server no longer registers the
service-mutating tools (create, fork, start, stop, resize,
update_password), so clients never see them and won't attempt them or
prompt for inputs that would only fail. Read tools and db_execute_query
(which connects read-only) stay registered.

A generic addTool wrapper skips registration for tools in
readOnlyGatedTools when the server is read-only; that slice is the single
source of truth, shared with the server instructions. The handler-level
common.CheckReadOnly guards are kept as a backstop for read_only being
toggled on mid-session.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aprimakina

internal/tiger/mcp/db_tools.go

@@ -107,8 +107,8 @@ func (DBExecuteQueryOutput) Schema() *jsonschema.Schema {
 
 // registerDatabaseTools registers database operation tools with comprehensive schemas and descriptions
 func (s *Server) registerDatabaseTools() {
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
-		Name:  "db_execute_query",
+	addTool(s, &mcp.Tool{
+		Name:  toolDBExecuteQuery,
 		Title: "Execute SQL Query",
 		Description: `Execute SQL queries against a service database.
 

internal/tiger/mcp/errors.go

@@ -1,5 +1,7 @@
 package mcp
 
+// readOnlyGatedTools are the service-mutating tools skipped in read-only mode.
+// Used by both addTool and buildServerInstructions.
 var readOnlyGatedTools = []string{
 	toolServiceCreate,
 	toolServiceFork,

internal/tiger/mcp/server.go

@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
+	"slices"
 	"strings"
 	"time"
 
@@ -27,14 +28,23 @@ const (
 type Server struct {
 	mcpServer       *mcp.Server
 	docsProxyClient *ProxyClient
+
+	// readOnly is captured from config at construction time. Handlers still call
+	// common.CheckReadOnly in case read_only is toggled on mid-session.
+	readOnly bool
+}
+
+// addTool registers an MCP tool, skipping readOnlyGatedTools in read-only mode.
+func addTool[In, Out any](s *Server, t *mcp.Tool, h mcp.ToolHandlerFor[In, Out]) {
+	if s.readOnly && slices.Contains(readOnlyGatedTools, t.Name) {
+		logging.Debug("Skipping write tool in read-only mode", zap.String("tool", t.Name))
+		return
+	}
+	mcp.AddTool(s.mcpServer, t, h)
 }
 
-// buildServerInstructions returns the `instructions` string the MCP SDK
-// sends to clients at initialize.
-//
-// Instructions are evaluated once at server start; toggling read_only
-// mid-session leaves the warning stale until the MCP client restarts. The
-// gate itself stays correct because handlers reload config per call.
+// buildServerInstructions returns the `instructions` string the MCP SDK sends
+// to clients at initialize. Evaluated once at server start, like tool registration.
 func buildServerInstructions(cfg *config.Config) string {
 	base := "Tiger MCP provides tools for creating, managing, and querying Tiger Cloud database services (managed TimescaleDB/PostgreSQL). " +
 		"Use it to provision and fork services, start/stop/resize instances, rotate credentials, fetch service logs, execute SQL queries, and search Tiger documentation."
@@ -43,9 +53,9 @@ func buildServerInstructions(cfg *config.Config) string {
 		return base
 	}
 	return base + " " +
-		"READ-ONLY MODE IS ENABLED. The following Tiger MCP tools will refuse to run: " +
-		strings.Join(readOnlyGatedTools, ", ") + ". " +
-		"Before asking the user to provide inputs for any of these operations, tell them read-only mode is on."
+		"READ-ONLY MODE IS ENABLED. Service-mutating tools (" +
+		strings.Join(readOnlyGatedTools, ", ") + ") are not available and are not registered, so do not offer them. " +
+		"db_execute_query connects read-only, so writes and DDL are rejected by the server."
 }
 
 // NewServer creates a new Tiger MCP server instance. The caller-supplied cfg
@@ -59,6 +69,7 @@ func NewServer(ctx context.Context, cfg *config.Config) (*Server, error) {
 
 	server := &Server{
 		mcpServer: mcpServer,
+		readOnly:  cfg != nil && cfg.ReadOnly,
 	}
 
 	// Register all tools (including proxied docs tools)

internal/tiger/mcp/server_test.go

@@ -0,0 +1,94 @@
+package mcp
+
+import (
+	"context"
+	"slices"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/timescale/tiger-cli/internal/tiger/config"
+)
+
+// alwaysRegisteredTools must be available regardless of read-only mode.
+var alwaysRegisteredTools = []string{
+	toolServiceList,
+	toolServiceGet,
+	toolServiceLogs,
+	toolDBExecuteQuery,
+}
+
+// registeredToolNames returns the tool names a server advertises over a real
+// client/server session. registerDocsProxy is skipped: it connects to a remote
+// server.
+func registeredToolNames(t *testing.T, readOnly bool) []string {
+	t.Helper()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+
+	s := &Server{
+		mcpServer: mcp.NewServer(&mcp.Implementation{
+			Name:    ServerName,
+			Title:   serverTitle,
+			Version: config.Version,
+		}, nil),
+		readOnly: readOnly,
+	}
+	s.registerServiceTools()
+	s.registerDatabaseTools()
+
+	clientTransport, serverTransport := mcp.NewInMemoryTransports()
+
+	serverSession, err := s.mcpServer.Connect(ctx, serverTransport, nil)
+	if err != nil {
+		t.Fatalf("server connect: %v", err)
+	}
+	t.Cleanup(func() { _ = serverSession.Close() })
+
+	client := mcp.NewClient(&mcp.Implementation{Name: "test-client"}, nil)
+	clientSession, err := client.Connect(ctx, clientTransport, nil)
+	if err != nil {
+		t.Fatalf("client connect: %v", err)
+	}
+	t.Cleanup(func() { _ = clientSession.Close() })
+
+	res, err := clientSession.ListTools(ctx, nil)
+	if err != nil {
+		t.Fatalf("list tools: %v", err)
+	}
+
+	names := make([]string, len(res.Tools))
+	for i, tool := range res.Tools {
+		names[i] = tool.Name
+	}
+	return names
+}
+
+func TestReadOnlyToolRegistration(t *testing.T) {
+	for _, tt := range []struct {
+		name             string
+		readOnly         bool
+		wantGatedPresent bool
+	}{
+		{"read-write registers all tools", false, true},
+		{"read-only skips gated tools", true, false},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			names := registeredToolNames(t, tt.readOnly)
+
+			// Read tools and the read-only-safe query tool are always present.
+			for _, name := range alwaysRegisteredTools {
+				if !slices.Contains(names, name) {
+					t.Errorf("expected tool %q to be registered, got %v", name, names)
+				}
+			}
+			// Service-mutating tools are present only in read-write mode.
+			for _, name := range readOnlyGatedTools {
+				if got := slices.Contains(names, name); got != tt.wantGatedPresent {
+					t.Errorf("gated tool %q registered = %v, want %v (got %v)", name, got, tt.wantGatedPresent, names)
+				}
+			}
+		})
+	}
+}

internal/tiger/mcp/service_tools.go

@@ -36,6 +36,7 @@ const (
 	toolServiceResize         = "service_resize"
 	toolServiceUpdatePassword = "service_update_password"
 	toolServiceLogs           = "service_logs"
+	toolDBExecuteQuery        = "db_execute_query"
 )
 
 // Wait timeout for MCP tool operations
@@ -419,7 +420,7 @@ func (ServiceLogsOutput) Schema() *jsonschema.Schema {
 // registerServiceTools registers service management tools with comprehensive schemas and descriptions
 func (s *Server) registerServiceTools() {
 	// service_list
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
+	addTool(s, &mcp.Tool{
 		Name:  toolServiceList,
 		Title: "List Database Services",
 		Description: "List all database services in your Tiger Cloud project. " +
@@ -434,7 +435,7 @@ func (s *Server) registerServiceTools() {
 	}, s.handleServiceList)
 
 	// service_get
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
+	addTool(s, &mcp.Tool{
 		Name:  toolServiceGet,
 		Title: "Get Service Details",
 		Description: "Get detailed information for a specific database service. " +
@@ -449,7 +450,7 @@ func (s *Server) registerServiceTools() {
 	}, s.handleServiceGet)
 
 	// service_create
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
+	addTool(s, &mcp.Tool{
 		Name:  toolServiceCreate,
 		Title: "Create Database Service",
 		Description: `Create a new database service in Tiger Cloud with specified type, compute resources, region, and HA options.
@@ -471,7 +472,7 @@ WARNING: Creates billable resources.`,
 	}, s.handleServiceCreate)
 
 	// service_fork
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
+	addTool(s, &mcp.Tool{
 		Name:  toolServiceFork,
 		Title: "Fork Database Service",
 		Description: `Fork an existing database service to create a new independent copy.
@@ -499,7 +500,7 @@ WARNING: Creates billable resources.`,
 	}, s.handleServiceFork)
 
 	// service_update_password
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
+	addTool(s, &mcp.Tool{
 		Name:  toolServiceUpdatePassword,
 		Title: "Update Service Password",
 		Description: "Update master password for 'tsdbadmin' user of a database service. " +
@@ -516,7 +517,7 @@ WARNING: Creates billable resources.`,
 	}, s.handleServiceUpdatePassword)
 
 	// service_start
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
+	addTool(s, &mcp.Tool{
 		Name:  toolServiceStart,
 		Title: "Start Database Service",
 		Description: `Start a stopped database service.
@@ -534,7 +535,7 @@ This operation starts a service that is currently in a stopped/paused state. The
 	}, s.handleServiceStart)
 
 	// service_stop
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
+	addTool(s, &mcp.Tool{
 		Name:  toolServiceStop,
 		Title: "Stop Database Service",
 		Description: `Stop a running database service.
@@ -552,7 +553,7 @@ This operation stops a service that is currently running. The service will trans
 	}, s.handleServiceStop)
 
 	// service_resize
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
+	addTool(s, &mcp.Tool{
 		Name:  toolServiceResize,
 		Title: "Resize Database Service",
 		Description: `Resize a database service by changing its CPU and memory allocation.
@@ -573,7 +574,7 @@ WARNING: Creates billable resource changes. Increasing resources will increase c
 	}, s.handleServiceResize)
 
 	// service_logs
-	mcp.AddTool(s.mcpServer, &mcp.Tool{
+	addTool(s, &mcp.Tool{
 		Name:  toolServiceLogs,
 		Title: "Get Service Logs",
 		Description: `View logs for a database service.