feat(cli): add disable-deployment, readonly, and env-only options to MCP server

Add three new options to the MCP server for better control:
- --disable-deployment: Disables deployment-related tools
- --readonly: Run in read-only mode, disabling all write operations (deployments, task triggering, project creation, run cancellation)
- --env-only: Restrict the MCP server to specific environments (dev, staging, prod, preview)

Key features:
- The --env-only flag allows fine-grained environment control and deprecates --dev-only (kept for backward compatibility)
- The --readonly flag overrides --disable-deployment since deployments are write operations
- Deployments are allowed to any environment that the MCP server has access to
- --dev-only and --env-only are mutually exclusive with proper error handling
- listDeploysTool correctly categorized as read-only operation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: hongkongkiwi

packages/cli-v3/src/commands/install-mcp.ts

@@ -114,6 +114,9 @@ const InstallMcpCommandOptions = z.object({
   projectRef: z.string().optional(),
   tag: z.string().default(cliTag),
   devOnly: z.boolean().optional(),
+  envOnly: z.string().optional(),
+  disableDeployment: z.boolean().optional(),
+  readonly: z.boolean().optional(),
   yolo: z.boolean().default(false),
   scope: z.enum(scopes).optional(),
   client: z.enum(clients).array().optional(),
@@ -137,7 +140,19 @@ export function configureInstallMcpCommand(program: Command) {
       "The version of the trigger.dev CLI package to use for the MCP server",
       cliTag
     )
-    .option("--dev-only", "Restrict the MCP server to the dev environment only")
+    .option("--dev-only", "Restrict the MCP server to the dev environment only (Deprecated: use --env-only dev)")
+    .option(
+      "--env-only <environments>",
+      "Restrict the MCP server to specific environments only. Comma-separated list of: dev, staging, prod, preview"
+    )
+    .option(
+      "--disable-deployment",
+      "Disable deployment-related tools in the MCP server. Overridden by --readonly."
+    )
+    .option(
+      "--readonly",
+      "Run MCP server in read-only mode. Disables all write operations. Overrides --disable-deployment."
+    )
     .option("--yolo", "Install the MCP server into all supported clients")
     .option("--scope <scope>", "Choose the scope of the MCP server, either user or project")
     .option(
@@ -193,6 +208,13 @@ export async function installMcpServer(
 
   writeConfigHasSeenMCPInstallPrompt(true);
 
+  // Check for mutual exclusivity
+  if (opts.devOnly && opts.envOnly) {
+    throw new OutroCommandError(
+      "--dev-only and --env-only are mutually exclusive. Please use only one. Consider using --env-only dev instead of --dev-only."
+    );
+  }
+
   const devOnly = await resolveDevOnly(opts);
 
   opts.devOnly = devOnly;
@@ -480,6 +502,18 @@ function resolveMcpServerConfig(
     args.push("--dev-only");
   }
 
+  if (options.envOnly) {
+    args.push("--env-only", options.envOnly);
+  }
+
+  if (options.disableDeployment) {
+    args.push("--disable-deployment");
+  }
+
+  if (options.readonly) {
+    args.push("--readonly");
+  }
+
   if (options.projectRef) {
     args.push("--project-ref", options.projectRef);
   }

packages/cli-v3/src/commands/mcp.ts

@@ -20,6 +20,9 @@ const McpCommandOptions = CommonCommandOptions.extend({
   projectRef: z.string().optional(),
   logFile: z.string().optional(),
   devOnly: z.boolean().default(false),
+  envOnly: z.string().optional(),
+  disableDeployment: z.boolean().default(false),
+  readonly: z.boolean().default(false),
   rulesInstallManifestPath: z.string().optional(),
   rulesInstallBranch: z.string().optional(),
 });
@@ -34,7 +37,19 @@ export function configureMcpCommand(program: Command) {
       .option("-p, --project-ref <project ref>", "The project ref to use")
       .option(
         "--dev-only",
-        "Only run the MCP server for the dev environment. Attempts to access other environments will fail."
+        "Only run the MCP server for the dev environment. Attempts to access other environments will fail. (Deprecated: use --env-only dev instead)"
+      )
+      .option(
+        "--env-only <environments>",
+        "Restrict the MCP server to specific environments only. Comma-separated list of: dev, staging, prod, preview. Example: --env-only dev,staging"
+      )
+      .option(
+        "--disable-deployment",
+        "Disable deployment-related tools. When enabled, deployment tools won't be available. This option is overridden by --readonly."
+      )
+      .option(
+        "--readonly",
+        "Run in read-only mode. Disables all write operations including deployments, task triggering, and project creation. Overrides --disable-deployment."
       )
       .option("--log-file <log file>", "The file to log to")
       .addOption(
@@ -106,11 +121,30 @@ export async function mcpCommand(options: McpCommandOptions) {
     ? new FileLogger(options.logFile, server)
     : undefined;
 
+  // Check for mutual exclusivity
+  if (options.devOnly && options.envOnly) {
+    logger.error("Error: --dev-only and --env-only are mutually exclusive. Please use only one.");
+    process.exit(1);
+  }
+
+  // Parse envOnly into an array if provided
+  let envOnly: string[] | undefined;
+  if (options.envOnly) {
+    envOnly = options.envOnly.split(',').map(env => env.trim());
+  } else if (options.devOnly) {
+    // For backward compatibility, convert devOnly to envOnly
+    envOnly = ['dev'];
+  }
+
   const context = new McpContext(server, {
     projectRef: options.projectRef,
     fileLogger,
     apiUrl: options.apiUrl ?? CLOUD_API_URL,
     profile: options.profile,
+    devOnly: options.devOnly,
+    envOnly,
+    disableDeployment: options.disableDeployment,
+    readonly: options.readonly,
   });
 
   registerTools(context);

packages/cli-v3/src/mcp/context.ts

@@ -19,6 +19,9 @@ export type McpContextOptions = {
   apiUrl?: string;
   profile?: string;
   devOnly?: boolean;
+  envOnly?: string[];
+  disableDeployment?: boolean;
+  readonly?: boolean;
 };
 
 export class McpContext {
@@ -184,4 +187,19 @@ export class McpContext {
   public get hasElicitationCapability() {
     return hasElicitationCapability(this.server);
   }
+
+  public isEnvironmentAllowed(environment: string): boolean {
+    // If envOnly is specified, use that
+    if (this.options.envOnly && this.options.envOnly.length > 0) {
+      return this.options.envOnly.includes(environment);
+    }
+
+    // For backward compatibility, check devOnly
+    if (this.options.devOnly) {
+      return environment === "dev";
+    }
+
+    // If neither is specified, all environments are allowed
+    return true;
+  }
 }

packages/cli-v3/src/mcp/tools.ts

@@ -18,23 +18,44 @@ import { getCurrentWorker, triggerTaskTool } from "./tools/tasks.js";
 import { respondWithError } from "./utils.js";
 
 export function registerTools(context: McpContext) {
-  const tools = [
+  // Always available read-only tools
+  const readOnlyTools = [
     searchDocsTool,
     listOrgsTool,
     listProjectsTool,
-    createProjectInOrgTool,
-    initializeProjectTool,
     getCurrentWorker,
-    triggerTaskTool,
     listRunsTool,
     getRunDetailsTool,
     waitForRunToCompleteTool,
-    cancelRunTool,
-    deployTool,
-    listDeploysTool,
     listPreviewBranchesTool,
+    listDeploysTool, // This is a read operation, not a write
   ];
 
+  // Write tools that are disabled in readonly mode
+  const writeTools = [
+    createProjectInOrgTool,
+    initializeProjectTool,
+    triggerTaskTool,
+    cancelRunTool,
+  ];
+
+  // Deployment tools that can be independently disabled
+  const deploymentTools = [
+    deployTool, // Only the actual deploy command is a write operation
+  ];
+
+  let tools = [...readOnlyTools];
+
+  // Add write tools if not in readonly mode
+  if (!context.options.readonly) {
+    tools = [...tools, ...writeTools];
+  }
+
+  // Add deployment tools if not disabled and not in readonly mode
+  if (!context.options.disableDeployment && !context.options.readonly) {
+    tools = [...tools, ...deploymentTools];
+  }
+
   for (const tool of tools) {
     context.server.registerTool(
       tool.name,

packages/cli-v3/src/mcp/tools/deploys.ts

@@ -18,9 +18,11 @@ export const deployTool = {
   handler: toolHandler(DeployInput.shape, async (input, { ctx, createProgressTracker, _meta }) => {
     ctx.logger?.log("calling deploy", { input });
 
-    if (ctx.options.devOnly) {
+    // Check if the deployment target environment is allowed
+    if (!ctx.isEnvironmentAllowed(input.environment)) {
+      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is only available for the dev environment. The deploy command is not allowed with the --dev-only flag.`
+        `This MCP server is restricted to the following environments: ${allowedEnvs}. You cannot deploy to ${input.environment}.`
       );
     }
 
@@ -118,9 +120,10 @@ export const listDeploysTool = {
   handler: toolHandler(ListDeploysInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling list_deploys", { input });
 
-    if (ctx.options.devOnly) {
+    if (!ctx.isEnvironmentAllowed(input.environment)) {
+      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is only available for the dev environment. You tried to access the ${input.environment} environment. Remove the --dev-only flag to access other environments.`
+        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
       );
     }
 

packages/cli-v3/src/mcp/tools/runs.ts

@@ -12,9 +12,10 @@ export const getRunDetailsTool = {
   handler: toolHandler(GetRunDetailsInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling get_run_details", { input });
 
-    if (ctx.options.devOnly && input.environment !== "dev") {
+    if (!ctx.isEnvironmentAllowed(input.environment)) {
+      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is only available for the dev environment. You tried to access the ${input.environment} environment. Remove the --dev-only flag to access other environments.`
+        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
       );
     }
 
@@ -69,9 +70,10 @@ export const waitForRunToCompleteTool = {
   handler: toolHandler(CommonRunsInput.shape, async (input, { ctx, signal }) => {
     ctx.logger?.log("calling wait_for_run_to_complete", { input });
 
-    if (ctx.options.devOnly && input.environment !== "dev") {
+    if (!ctx.isEnvironmentAllowed(input.environment)) {
+      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is only available for the dev environment. You tried to access the ${input.environment} environment. Remove the --dev-only flag to access other environments.`
+        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
       );
     }
 
@@ -122,9 +124,10 @@ export const cancelRunTool = {
   handler: toolHandler(CommonRunsInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling cancel_run", { input });
 
-    if (ctx.options.devOnly && input.environment !== "dev") {
+    if (!ctx.isEnvironmentAllowed(input.environment)) {
+      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is only available for the dev environment. You tried to access the ${input.environment} environment. Remove the --dev-only flag to access other environments.`
+        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
       );
     }
 
@@ -162,9 +165,10 @@ export const listRunsTool = {
   handler: toolHandler(ListRunsInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling list_runs", { input });
 
-    if (ctx.options.devOnly && input.environment !== "dev") {
+    if (!ctx.isEnvironmentAllowed(input.environment)) {
+      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is only available for the dev environment. You tried to access the ${input.environment} environment. Remove the --dev-only flag to access other environments.`
+        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
       );
     }
 

packages/cli-v3/src/mcp/tools/tasks.ts

@@ -11,9 +11,10 @@ export const getCurrentWorker = {
   handler: toolHandler(CommonProjectsInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling get_current_worker", { input });
 
-    if (ctx.options.devOnly && input.environment !== "dev") {
+    if (!ctx.isEnvironmentAllowed(input.environment)) {
+      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is only available for the dev environment. You tried to access the ${input.environment} environment. Remove the --dev-only flag to access other environments.`
+        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
       );
     }
 
@@ -90,9 +91,10 @@ export const triggerTaskTool = {
   handler: toolHandler(TriggerTaskInput.shape, async (input, { ctx }) => {
     ctx.logger?.log("calling trigger_task", { input });
 
-    if (ctx.options.devOnly && input.environment !== "dev") {
+    if (!ctx.isEnvironmentAllowed(input.environment)) {
+      const allowedEnvs = ctx.options.envOnly?.join(", ") || "dev";
       return respondWithError(
-        `This MCP server is only available for the dev environment. You tried to access the ${input.environment} environment. Remove the --dev-only flag to access other environments.`
+        `This MCP server is restricted to the following environments: ${allowedEnvs}. You tried to access the ${input.environment} environment.`
       );
     }