googleapis/mcp-toolbox · error

MCP Auth cannot be enabled together with the legacy HTTP API

Error message

MCP Auth cannot be enabled together with the legacy HTTP API (--enable-api)

What it means

MCP auth (tools authentication) and the legacy HTTP API (--enable-api) are mutually exclusive runtime modes in MCP Toolbox. When mcpAuthEnabled is true, the code checks opts.Cfg.EnableAPI and refuses to start, because the legacy API would expose tools without the MCP auth path. The command aborts before the server is created.

Source

Thrown at cmd/root.go:450

	}()

	isCustomConfigured, err := opts.LoadConfig(ctx, &internal.ConfigParser{})
	if err != nil {
		return err
	}

	// Validate ToolboxUrl if MCP Auth is enabled
	var mcpAuthEnabled bool
	for _, authSvc := range opts.Cfg.AuthServiceConfigs {
		if authSvc.IsMCPEnabled() {
			mcpAuthEnabled = true
			break
		}
	}

	if mcpAuthEnabled {
		if opts.Cfg.EnableAPI {
			errMsg := fmt.Errorf("MCP Auth cannot be enabled together with the legacy HTTP API (--enable-api)")
			opts.Logger.ErrorContext(ctx, errMsg.Error())
			return errMsg
		}
		if opts.Cfg.ToolboxUrl == "" {
			opts.Cfg.ToolboxUrl = os.Getenv("TOOLBOX_URL")
		}
		if opts.Cfg.ToolboxUrl == "" {
			errMsg := fmt.Errorf("MCP Auth is enabled but Toolbox URL is missing. Please provide it via --toolbox-url flag or TOOLBOX_URL environment variable")
			opts.Logger.ErrorContext(ctx, errMsg.Error())
			return errMsg
		}
	}

	// start server
	s, err := server.NewServer(ctx, opts.Cfg)
	if err != nil {
		errMsg := fmt.Errorf("toolbox failed to initialize: %w", err)
		opts.Logger.ErrorContext(ctx, errMsg.Error())

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Remove the --enable-api flag from the command line or config when MCP auth is enabled
2. If both endpoints are needed, run two toolbox instances: one with MCP auth, one legacy
3. Update deployment scripts/compose files to drop legacy API usage

Example fix

// before
./toolbox --enable-api --tools-file tools.yaml --auth ...
// after
./toolbox --tools-file tools.yaml --auth ...

// shell pre-check before launching toolbox
if grep -q -- '--enable-api' <<< "$TOOLBOX_ARGS" && [[ "$TOOLBOX_ARGS" == *--mcp-auth* || -n "$MCP_AUTH" ]]; then
  echo "--enable-api conflicts with MCP auth; remove --enable-api" >&2
  exit 1
fi

When it happens

Trigger: Running toolbox with MCP auth flags enabled together with --enable-api (EnableAPI=true in the server config).

Common situations: Operators migrating from the legacy HTTP API to MCP-authenticated MCP servers who keep the old --enable-api flag in a script, systemd unit, or Dockerfile CMD alongside new auth flags.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• failed to check auth requirements: %w
• MCP Auth is enabled but Toolbox URL is missing. Please provi
• client authorization is not supported
• error retrieving configuration file: %w
• invalid prebuilt config format '%s'. Did you mean '%s/%s'? U

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/5330e2d7f3832012. Report an issue: GitHub.